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Preface 





In part, this book came into being because Len hates using online docu- 
mentation. He likes to read while sitting at his kitchen table sipping tea. 
He likes to read sitting in his living room listening to soft Baroque music. 
He does not like to read documentation while staring at his computer 
monitor. 


Len needed some of the documentation presented in this book for his In- 
stant OS/2! character-mode programming title. Len called IBM tech sup- 
port. After a short waiting period, he became impatient and then called 
Marc for help. 


Marc told Len about the .INF file IBM had released electronically in re- 
sponse to requests for VIO/KBD/MOU documentation. After Len began 
viewing the file, he reached for some aspirin. 


Len begged Marc to write am .INF to ASCII conversion program so he could 
print out the VIO/KBD/MOU docs. With the help of a document written by 
Carl Hauser describing the .INF format, Marc took up the challenge and a few 
days later Len had his precious hardcopy of the VIO/KBD/MOU functions. 


Len reasoned that he might not be the only person on the planet who prefers 
hardcopy to online documentation, so we decided to produce the book. 


XI 
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Introduction 





This book documents the OS/2 KBD/MOU/VIO subsystems. For what- 
ever reason, IBM did not include documentation for the KBD/MOU/VIO 
calls in their OS/2 2.0 Technical Library. Although the current trend is to- 
ward GUI (Graphical User Interface) applications, there is still a place for 
full-screen character-mode programs. This book is designed to facilitate 
the creation (and perhaps more important, porting) of full-screen charac- 
ter-mode programs to run in OS/2 character-mode sessions. 


The KBD/MOU/VIO subsystems provide a rich set of primitives for creat- 
ing character-mode user interfaces. Unlike MS/DOS, OS/2 is a real oper- 
ating system, and as such you generally need to go through the OS to get 
to the hardware. Where in MS/DOS you scribbled characters and at- 
tributes into addresses B800:0000-B800:07D0 (for example) to make 
characters appear on the screen, in OS/2 you must use the VIO calls. 
While you might lose some performance and flexibility, you gain enor- 
mously in terms of program reliability. 


It’s always fun to program the bare metal, but it’s dangerous. Real operat- 
ing systems like OS/2 provide a safety buffer between the programmer 
and the hardware. 


This book is based on the .INF documentation provided by IBM. We have 
significantly reformatted the contents to suit the printed page. An impor- 
tant addition is the inclusion of #fdefine constant names for bit masks and 
predefined values (where they are defined in the OS2 include files). In ad- 
dition, we have added notes in some places where the actual behavior of 
the calls appears to deviate from the behavior documented by IBM. 


We have chosen to orient the layout of the book to C programmers. As- 
sembly language programmers are becoming a rare, though hardy, breed. 
We expect that they will be able to extract whatever information they need 
from the C call descriptions. 


The book is organized into three parts. Part One describes the KBD inter- 
face. Part Two describes the MOU calls. Part Three describes the VIO sys- 
tem. The appendix gives a listing of the error codes returned by the 
KBD/MOU/VIO calls and their descriptions. 


We hope that the information provided in this book will greatly ease the 
task of creating full screen character-mode programs that will run in an 
OS/2 full-screen session. 
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Keyboard (KBD) 
functions 


This part describes the OS/2 keyboard API interface. 


Notes 


e Calls marked xPM are not supported by Presentation Manager, and 
must not be used by Presentation Manager applications. An error 
code is returned if any of these calls are issued. 

e Calls marked xWPM are not windowable and are not supported by 
Presentation Manager. They can be used in OS/2 mode. 

e Calls marked FAPI are present in the Family API. 


Table 1-1 Keyboard call list 


Function call Icon 
KbdCharIn FAPI xPM 
KbdClose xPM 
KbdDeRegister xXWPM 
KbdFlushBuffer FAPI xPM 
KbdFreeFocus xPM 
KbdGetCp xPM 
KbdGetFocus xPM 
KbdGetStatus FAPI xPM 
KbdOpen xPM 
KbdPeek FAPI xPM 
KbdRegister xXWPM 
KbdSetCp xPM 
KbdSetCustxt xPM 
KbdSetFgnd xPM 
KbdSetStatus FAPI xPM 
KbdStringIn FAPI xPM 
KbdSynch xWPM 
KbdXlate xPM 
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KbodChariIn (FAPI, xPM) 


Description 


This call returns a character data record from the keyboard. 


+#define INCL_KBD 
einc ude <os2.h> 


USHORT KbdCharIn(PKBDKEYINFO pkbci, USHORT fWait, HKBD hkbd); 


pkbci (PKBDKEYINFO) - output 
Address of the character data structure. 


chChar (UCHAR) 
ASCII character code. The scan code received from the keyboard 
is translated to the ASCII character code. 


chScan (UCHAR) 
Code received from the keyboard. The scan code received from the 
keyboard is translated to the ASCII character code. 


fbStatus (UCHAR) 
State of the keystroke event. 


Bit Description 


7-6 00 = Undefined 
Ol = Final character, interim character flag off 
(fobStatus & KBDTRF_FINAL_ CHAR _IN) 
&& !(fobStatus & KBDTRF_INTERIM_CHAR _IN) 
5 10 = Interim character 
'(fbStatus & KBDTRF_FINAL_CHAR_IN) 
&& (fbStatus & KBDTRF_INTERIM_CHAR IN) 
11 = Final character, interim character flag on. 
(fbStatus & KBDTRF_FINAL_CHAR _ IN) 
&& (foStatus & KBDTRF_INTERIM_ CHAR IN) 
1 = Immediate conversion requested. 
(fbStatus & KBDTRF_CONVERSION_REQUEST) 
4-2 Reserved. 
1 O= Scan code is a character. 
1 = Scan code is not a character but is an extended 
key code from the keyboard. 
O 1 = Shift status returned without character. 
(fbStatus & KBDTRF_SHIFT_KEY_IN) 


bDNIsShift (CUCHAR) 
NLS shift status. Reserved, set to zero. 


Keyboard (KBD) functions 3 


fsState (USHORT ) 
Shift key status. 


Bit 
15 
14 
13 
12 
hak 
10 


O10) N © © 


Orb W 


Description 

SysReq key down 
CapsLock key down 
NumLock key down 
ScrollLock key down 
Right Alt key down 
Right Ctrl key down 
Left Alt key down 
Left Ctrl key down 
Insert on 

CapsLock on 
NumLock on 
ScrollLock on 


Either Alt key down 
Either Ctrl key down 
Left Shift key down 
Right Shift key down 


time (ULONG) 


(fsState & KBDSTF_SYSREQ) 
(fsState & KBDSTF_CAPSLOCK) 
(fsState & KBDSTF_NUMLOCK) 
(fsState & KBDSTF_SCROLLLOCK) 
(fsState & KBDSTF_RIGHTALT) 
(fsState & KBDSTF_RIGHTCONTROL) 
(fsState & KBDSTF_LEFTALT) 
(fsState & KBDSTF_LEFTCONTROL) 
(fsState & KBDSTF_INSERT_ON) 
(fsState & KBDSTF_CAPSLOCK_ON) 
(fsState & KBDSTF_NUMLOCK_ON) 
(fsState & KBDSTF_SCROLL 
LOCK_ON) 
(fsState & KBDSTF_ALT) 
(fsState & KBDSTF_CONTROL) 
(fsState & KBDSTF_LEFTSHIFT) 
(fsState & KBDSTF_RIGHTSHIFT) 


Time stamp indicating when a key was pressed. It is specified in 
milliseconds from the time the system was started. 


fWait (USHORT) - input 
Wait if a character is not available. 


Value Definition 


O 


1 


Requestor waits for a character if one is not available. 
({Wait == IO_WAIT) 
Requestor gets an immediate return if no character is available. 
(fWait == IO_NOWAIT) 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


NO_ERROR 
ERROR_KBD_INVALID_IOWAIT 
ERROR_KBD_INVALID_HANDLE 
ERROR_KBD_FOCUS_REQUIRED 
ERROR_KBD_KEYBOARD_BUSY 
ERROR_KBD_DETACHED 


O 
375 
439 
445 
447 
464 
504 


ERROR_KBD_EXTENDED_SG 
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Remarks 


On an enhanced keyboard, the secondary enter key returns the normal 
character ODH and a scan code of EOH. 


Double-byte character codes (DBCS) require two function calls to obtain 
the entire code. 


If shift report is set with KbdSetStatus, the CharData record returned re- 
flects changed shift information only. 


Extended ASCII codes are identified with the status byte, bit 1 on and the 
ASCII character code being either OOH or EOH. Both conditions must be 
satisfied for the character to be an extended keystroke. For extended ASCII 
codes, the scan code byte returned is the second code (extended code). 
Usually the extended ASCII code is the scan code of the primary key that 
was pressed. 


A thread in the foreground session that repeatedly polls the keyboard with 
KbdCharIn (with no wait), can prevent all regular priority class threads 
from executing. If polling must be used and a minimal amount of other 
processing is being performed, the thread should periodically yield to the 
CPU by issuing a DosSleep call for an interval of at least 5 milliseconds. 


Family API considerations 


Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following restrictions apply to KbdCharIn when coding in the 
DOS mode: 


e The CharData structure includes everything except the time stamp. 
e Interim character is not supported 

e Status can be O or 40H 

e KbdHandle is ignored. 
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KbdClose (xPM) 


Description 


This call closes the existing logical keyboard identified by the keyboard 
handle. 


ftdefine INCL_KBD 
include <os2.h> 


USHORT KbdClose (HKBD hkbd) ; 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


O NO_ERROR 
439 ERROR_KBD_INVALID_HANDLE 
464 ERROR_KBD_ DETACHED 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


KbdClose blocks while another thread has the keyboard focus (by way of 
KbdGetFocus) until the thread with the focus issues KbdFreeFocus. There- 
fore, to prevent KbdClose from blocking, it is recommended that KbdClose 
be issued only while the current thread has the focus. For example: 


KbdGetFocus Wait until focus available on handle O. 
KbdClose Close a logical keyboard handle. 

KbdClose Close another logical keyboard handle. 
KbdClose Close still another logical keyboard handle. 
KbdFreeFocus Give up the focus on handle O. 
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KodDeRegister (xWPM) 


Description 
This call deregisters a keyboard subsystem previously registered within a ses- 
sion. Only the process that issued the KbdRegister may issue KbdDeRegister. 


define INCL_KBD 
4#FAinclude <os2.h> 


USHORT KbdDeRegister (void); 


Return value 


O NO_ERROR 
411 ERROR_KBD_DEREGISTER 
464 ERROR_KBD_DETACHED 
504 ERROR_KBD_EXTENDED_SG 
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KbodFlushBuffer (FAPI, xPM) 


Description 
This call clears the keystroke buffer. 


4edefine INCL_KBD 
#include <os2.h> 


USHORT KbdFlushBuffer (HKBD hkbd); 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


O NO_ERROR 
439 ERROR_KBD_INVALID_HANDLE 
445 ERROR_KBD_FOCUS_REQUIRED 
447 ERROR_KBD_KEYBOARD_BUSY 
464 ERROR_KBD_DETACHED 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


KbdFlushBuffer completes when the handle has access to the physical 
keyboard (focus), or is equal to zero and no other handle has the focus. 


Family API considerations 


Some options operate differently in the DOS mode than in the OS/2 mode. 
The KbdHandle is ignored when coding in the DOS mode. 
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KbodFreeFocus (xPM) 


Description 
This call frees the logical-to-physical keyboard bond created by KbdGetFocus. 


ftdefine INCL_KBD 
-include <os2.h> 


USHORT KbdFreeFocus (HKBD hkbd); 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


QO NO_ERROR 
439 ERROR_KBD_INVALID_HANDLE 
445 ERROR_KBD_FOCUS_REQUIRED 
464 ERROR_KBD_DETACHED 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


KbdFreeFocus may be replaced by issuing KbdRegister. Unlike other key- 
board subsystem functions, the replaced KbdFreeFocus is called only if 
there is an outstanding focus. 
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KodGetCp (xPM) 


Description 


This call allows a process to query the code page being used to translate 
scan codes to ASCII characters. 


4edefine INCL_KBD 
include <os?.h> 


USHORT KbdGetCp (ULONG ulReserved, PUSHORT pidCP, HKBD hkbd); 


ulReserved (ULONG) - input 
Reserved and must be set to zero. 


pidCP (PUSHORT) - output 
Address of the code page ID located in the application’s data area. The 
keyboard support copies the current code page ID for a specified key- 
board handle into this word. The code page ID is equivalent to one of 
the code page IDs specified in the CONFIG.SYS CODEPAGE = state- 
ment or OOOO. 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


O NO_ERROR 
373 ERROR_KBD_PARAMETER 
439 ERROR_KBD_INVALID_HANDLE 
445 ERROR_KBD_FOCUS_REQUIRED 
447 ERROR_KBD_KEYBOARD_BUSY 
464 ERROR_KBD_DETACHED 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


The CodePageID is the currently active keyboard code page. A value of O in- 
dicates the code page translation table in use is the ROM code page trans- 
lation table provided by the hardware. 


10 Keyboard (KBD) functions 


KodGetFocus (xPM) 


Description 
This call binds the logical keyboard to the physical keyboard. 


define INCL_KBD 
4#Finclude <os2.h> 


USHORT KbdGetFocus (USHORT fWait, HKBD hkbd); 


fWait (USHORT) - input 
Wait if the physical keyboard is already in use by a logical keyboard. 


Value Definition 


O Indicates that the caller wants to wait for the bond. 
({(Wait == IO_WAIT) 

1 Indicates that the caller does not want to wait for the bond. 
(fWait == IO_NOWAIT) 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


QO NO_ERROR 
439 ERROR_KBD_INVALID_HANDLE 
446 ERROR_KBD_FOCUS_ALREADY_ACTIVE 
447 ERROR_KBD_KEYBOARD_ BUSY 
464 ERROR_KBD_DETACHED 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


The keyboard handle identifies which logical keyboard to bind to. If the 
physical keyboard is not bound to a logical or default keyboard, then the 
bind proceeds immediately. The logical keyboard, identified by the handle, 
receives all further keystrokes from the physical keyboard. If the physical 
keyboard is already in use by a logical keyboard, then the thread issuing 
KbdGetFocus waits until the bond can be made. Waiting threads do not ex- 
ecute in any definable order. 
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KbdGetHWID (xPM) 


Description 


Returns the attached keyboard’s hardware-generated Identification value. 


4edefine INCL_KBD 
#include <oszZ.h> 


USHORT KbdGetHWID (PKBDHWID pkbdhwid, HKBD hkbd); 


pkbdhwid (PKBDHWID) - input 


Pointer to the caller’s data area where the following structure and 
data values are: 


cb (USHORT) - input/output 


On input, this field should contain the length of the KeyboardID 
structure. The minimum input length value allowed is 2. On out- 
put, this field contains the actual number of bytes returned. 


idkbd (USHORT) - output 


OS/2 supported keyboards and their hardware generated IDs are 
as follows: 


ID Keyboard 


OOOOH Undetermined keyboard type 

OOO1H PC-AT standard keyboard 

AB41H 101-key enhanced keyboard 

AB41H 102-key enhanced keyboard 

AB54H_ 88- and 89-key enhanced keyboards 
AB85H_ 122-key enhanced keyboard 


usReservedl (USHORT ) 


Reserved and returned set to zero. 


usReserved2 (USHORT ) 


Reserved and returned set to zero. 


hkbd (HKBD) - input 
Word identifying the logical keyboard. 


Return value 


O 
373 
447 
464 
504 


NO_ERROR 
ERROR_KBD_PARAMETER 
ERROR_KBD_KEYBOARD_BUSY 
ERROR_KBD_DETACHED 
ERROR_KBD_EXTENDED_SG 
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Remarks 

In past OS/2 releases, all keyboards could be supported by knowing the 
hardware family information available with keyboard IOCTL 77H. How- 
ever, with the addition of the 122-key keyboard, recognition was not con- 
tainable by hardware family information alone. The 122-key keyboard has 
a number of differences from other keyboards. Therefore, applications per- 
forming keystroke specific functions might need to determine specifically 
which keyboard is attached. 


This function is of particular usefulness for applications providing Custom 
Translate Tables and mapping keyboard layouts. 
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KbdGetStatus (FAPI, xPM) 


Description 


This call gets the current state of the keyboard. 


define INCL_KBD 
Fittclude <os2.he 


USHORT KbdGetStatus (PKBDINFO pkbdinfo, HKBD hdbd); 


pkbdinfo (PKBDINFO) - output 
Address of the keyboard status structure: 


cb (USHORT) 
Length, in bytes, of this data structure, including length. 


10 Only valid value. 


fsMask (USHORT) 
State as follows: 


Bit 
15-9 
8 


7 


Description 

Reserved, set to zero. 

Shift return is on. 

(fsMask & KEYBOARD_SHIFT_REPORT) 
Length of the turnaround character (meaningful only if 
bit 6 is on). 

(fSsMask & KEYBOARD 2B TURNAROUND) 
Turnaround character is modified. 

(fsMask & KEYBOARD_MODIFY_TURNAROUND) 
Interim character flags are modified. 
(fSMask & KEYBOARD_MODIFY_INTERIM) 
Shift state is modified. 

(fsMask & KEYBOARD MODIFY_STATE) 
ASCII mode is on. 

(fSMask & KEYBOARD_ASCIIMODE) 
Binary mode is on. 

(fsMask & KEYBOARD_BINARY_MODE) 
Echo off. 

(fsMask & ECHO_OFF) 

Echo on. 

(fsMask & ECHO_ON) 


chTurnAround (USHORT) 
Definition of the turnaround character. In ASCII and extended- 
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ASCII format, the turnaround character is defined as the carriage 
return. In ASCII format only, the turnaround character is defined 
in the low-order byte. 


fsInterim (USHORT ) 
Interim character flags: 


Bit 


15-8 


4—0 


Description 
NLS shift state. 


7 Interim character flag is on. 
6 Reserved, set to zero. 
5 Application requested immediate conversion. 


fsState (USHORT) 
Shift state as follows: 


Bit 
15 
14 
13 
12 
Li 
10 


OrFNWAKHOUAN @® O 


Description 

SysReg key down 
CapsLock key down 
NumLock key down 
ScrollLock key down 
Right Alt key down 
Right Ctrl key down 
Left Alt key down 
Left Ctrl key down 
Insert on 

CapsLock on 
NumLock on 
ScrollLock on 

Either Alt key down 
Either Ctrl key down 
Left Shift key down 
Right Shift key down 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


NO_ERROR 
ERROR_KBD_INVALID_LENGTH 
ERROR_KBD_INVALID_HANDLE 
ERROR_KBD_FOCUS_REQUIRED 
ERROR_KBD_KEYBOARD_BUSY 
ERROR_KBD_DETACHED 
ERROR_KBD_EXTENDED_SG 


O 
376 
439 
445 
447 
464 
504 


Reserved, set to zero. 


(fsState & KBDSTF_SYSREQ) 

(fsState & KBDSTF_CAPSLOCK) 
(fsState & KBDSTF_NUMLOCK) 
(fsState & KBDSTF_SCROLLLOCK) 
(fsState & KBDSTF_RIGHTALT) 
(fsState & KBDSTF_RIGHTCONTROL) 
(fsState & KBDSTF_LEFTALT) 
(fsState & KBDSTF_LEFTCONTROL) 
(fsState & KBDSTF_INSERT_ON) 
(fsState & KBDSTF_CAPSLOCK_ON) 
(fsState & KBDSTF_NUMLOCK_ON) 
(fsState & KBDSTF_SCROLLLOCK_ON) 
(fsState & KBDSTF_ALT) 

(fsState & KBDSTF_CONTROL) 
(fsState & KBDSTF_LEFTSHIFT) 
(fsState & KBDSTF_RIGHTSHIFT) 
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Remarks 


The initial state of the keyboard is established by the system at application 
load time. Some default states may be modified by the application through 
KbdSetStatus. KbdGetStatus returns only those keyboard parameters ini- 
tially set by KbdSetStatus. The returned parameters are 


e Input mode 

e Interim character flags 
e Shift state 

e Echo state 

e Turnaround character 


KbdGetStatus completes only when the handle has access to the physical 
keyboard (focus) or the handle is O and no other handle has the focus. 


Family API considerations 


Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following restrictions apply to KbdGetStatus when coding in 
the DOS mode: 


e Interim character is not supported 

e Turnaround character is not supported 
e NLS_SHIFT_STATE is always NULL. 

e KbdHandle is ignored. 
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KbdOpen (xPM) 


Description 
This call creates a new logical keyboard. 


define INCL_KBD 
#include <os2.h> 


USHORT KbdOpen (PHKBD phkbd); 


phkbd (PHKBD) - output 
Address of the logical keyboard. 


Return Value 


O 
440 
44] 
464 
504 


NO_ERROR 
ERROR_KBD_NO_MORE_HANDLE 
ERROR_KBD_CANNOT_CREATE_KCB 
ERROR_KBD_DETACHED 
ERROR_KBD_EXTENDED_SG 


Remarks 


KbdOpen blocks while another thread has the keyboard focus (by way of 
KbdGetFocus) until the thread with the focus issues KbdFreeFocus. There- 


fore 


, to prevent Kbd0pen from blocking, it is recommended that KbdOpen be 


issued only while the current thread has the focus. For example: 


KbdGetFocus Wait until focus available on handle O 


KbdOpen Get a logical keyboard handle 
KbdOpen Get another logical keyboard handle 
KbdOpen Get yet another logical keyboard handle 


KbdFreeFocus Give up the focus on handle 0. 
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KbdPeek (FAPI, xPM) 


Description 


This call returns any available character data record from the keyboard 
without removing it from the buffer. 


4edefine INCL_KBD 
#include <os2.h> 


USHORT KbdPeek (PKBDKEYINFO pkbci, HKBD hkbd); 


pkbci (PKBDKEYINFO) - output 
Address of the character data information: 


chChar (UCHAR) 
ASCII character code. The scan code received from the keyboard is 
translated to the ASCII character code. 


chScan (UCHAR) 
Code received from the keyboard hardware. 


fbStatus (UCHAR) 
State of the keystroke event: 


Bit Description 


7-6  OO= Undefined 
Ol = Final character, interim character flag off 
(fbStatus & KBDTRF_FINAL_CHAR_IN) 
&& !(foStatus & KBDTRF_INTERIM_CHAR_IN) 
10 = Interim character 
'(fbStatus & KBDTRF_FINAL_CHAR_IN) 
&& (foStatus & KBDTRF_INTERIM_CHAR_IN) 
11 = Final character, interim character flag on. 
(fbStatus & KBDTRF_FINAL_CHAR_IN) 
&& (foStatus & KBDTRF_INTERIM_CHAR_IN) 
5 1 = Immediate conversion requested. 
(fbStatus & KBDTRF_CONVERSION_REQUEST) 
4-2 Reserved. 


1 O= Scan code is a character. 
1 = Scan code is not a character; is an extended key code 
from the keyboard. 
O 1= Shift status returned without character. 


(fbStatus & KBDTRF_SHIFT_KEY_IN) 


bNIsShift (CUCHAR) 
NLS shift status. Reserved, set to zero. 
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fsState 


(USHORT ) 


Shift key status. 


Bit 
15 
14 
13 
12 
11 
10 


OrFRFNWHOAN ®W O 


Description 

SysReg key down 
CapsLock key down 
NumLock key down 
ScrollLock key down 
Right Alt key down 
Right Ctrl key down 
Left Alt key down 
Left Ctrl key down 
Insert on 

CapsLock on 
NumLock on 
ScrollLock on 

Either Alt key down 
Either Ctrl key down 
Left Shift key down 
Right Shift key down 


time (ULONG) 


(fsState & KBDSTF_SYSREQ) 
(fsState & KBDSTF_CAPSLOCK) 
(fsState & KBDSTF_NUMLOCK) 
(fsState & KBDSTF_SCROLLLOCK) 
(fsState & KBDSTF_RIGHTALT) 
(fsState & KBDSTF_RIGHTCONTROL) 
(fsState & KBDSTF_LEFTALT) 
(fsState & KBDSTF_LEFTCONTROL) 
(fsState & KBDSTF_INSERT_ON) 
(fsState & KBDSTF_CAPSLOCK_ON) 
(fsState & KBDSTF_NUMLOCK_ON) 
(fsState & KBDSTF_SCROLLLOCK_ON) 
(fsState & KBDSTF_ALT) 

(fsState & KBDSTF_CONTROL) 
(fsState & KBDSTF_LEFTSHIFT) 
(fsState & KBDSTF_RIGHTSHIFT) 


Time stamp indicating when a key was pressed. It is specified in 
milliseconds from the time the system was started. 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


NO_ERROR 
ERROR_KBD_INVALID_HANDLE 
ERROR_KBD_FOCUS_REQUIRED 
ERROR_KBD_KEYBOARD_BUSY 
ERROR_KBD_DETACHED 
ERROR_KBD_EXTENDED_SG 


O 
439 
445 
447 
464 
504 


Remarks 


On an enhanced keyboard, the secondary enter key returns the normal 
character ODH and a scan code of EOH. 


Double-byte character codes (DBCS) require two function calls to obtain 
the entire code. 


If shift report is set with KbdSetStatus the CharData record returned, re- 
flects changed shift information only. 
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Extended ASCII codes are identified with the status byte, bit 1 on and the 
ASCII character code being either OOH or EOH. Both conditions must be 
satisfied for the character to be an extended keystroke. For extended ASCII 
codes, the scan code byte returned is the second code (extended code). 
Usually the extended ASCII code is the scan code of the primary key that 
was pressed. 


A thread in the foreground session that repeatedly polls the keyboard with 
KbdCharIn (with no wait), can prevent all regular priority class threads 
from executing. If polling must be used and a minimal amount of other 
processing is being performed, the thread should periodically yield the 
CPU by issuing a DosSleep call for an interval of at least 5 milliseconds. 


Family API considerations 


Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following restrictions apply to KbdPeek when coding for the 
DOS mode: 


e The CharData structure includes everything except the time stamp. 
e Interim character is not supported. 

e Status can be O or 1. 

¢ KbdHandle is ignored. 
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KbdRegister (xWPM) 


Description 


This call registers a keyboard subsystem within a session. 


dedefine INCL_KBD 
+#include <os2.h> 


USHORT KbdRegister (PSZ pszModName, PSZ pszEntryPt, ULONG FunMask); 


pszModName (PSZ) - input 
Address of the dynamic link module name. Maximum length is 9 bytes 
(including ASCIIZ terminator). 


pszEntryPt (PSZ) - input 
Address of the dynamic link entry point name of a routine that receives 
control when any of the registered functions are called. Maximum 
length is 33 bytes (including ASCIIZ terminator). 


FunMask (ULONG) - input 
A bit mask where each bit identifies a keyboard function being regis- 
tered. The bit values are 


Bit Registered function Mask 


31-15 Reserved, must be set to zero. 
14 KbdGetHWId 


13 KbdSetCustxt (FunMask & KR_KBDSETCUSTAXT) 
12 KbdXxlate (FunMask & KR_KBDXLATE) 
ll KbdSetCp (FunMask & KR_KBDSETCP) 
10 KbdGetCp (FunMask & KR_KBDGETCP) 
9 KbdFreeFocus (FunMask & KR_KBDFREEFOCUS) 
8 KbdGetFocus (FunMask & KR_GETFOCUS) 
7 KbdClose (FunMask & KR_KBDCLOSE) 
6 KbdOpen (FunMask & KR_KBDOPEN) 
5 KbdStringIn (FunMask & KR_KBDSTRINGIN) 
4 KbdSetStatus (FunMask & KR_KBDSETSTATUS) 
Me KbdGetStatus (FunMask & KR_KBDGETSTATUS) 
a KbdFlushBuffer (FunMask & KR_KBDFLUSHBUFFER) 
1 KbdPeek (FunMask & KR_KBDPEEK) 
O KbdCharIn (FunMask & KR_KBDCHARIN) 


Return value 


O NO_ERROR 
408 ERROR_KBD_INVALID_ASCIIZ 
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409 
410 
464 
504 


ERROR_KBD_INVALID_MASK 
ERROR_KBD_REGISTER 
ERROR_KBD_DETACHED 
ERROR_KBD_EXTENDED_SG 


Remarks 


There can be only one KbdRegister call outstanding for each session with- 
out an intervening KbdDeRegister. KbdDeRegister must be issued by the 
same process that issued the KbdRegister. 
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Description 


This call allows the process to set the code page used to translate 
keystrokes received from the keyboard. 


#tdefine INCL_KBD 
Fine ude <osZ.h> 


KbdSetCp (xPM) 


USHORT KbdSetCp (USHORT usReserved, USHORT pidCP, HKBD hkbd); 


usReserved (USHORT) - input 
Reserved and must be set to zero. 


pidCP (USHORT) - input 
CodePageID represents a code-page ID in the application’s data area. 
The code-page ID must be equivalent to one of the code-page IDs spec- 
ified on the CONFIG.SYS CODEPAGE = statement or OOOO. If the code- 
page ID does not match one of the IDs on the CODEPAGE = statement, 
an error results. The code-page word must have one of these code-page 
identifiers: 


Identifier Description 


O Resident code page 
437 IBM PC US 437 
850 Multilingual 
860 Portuguese 
863 Canadian-French 
865 Nordic 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


O 
439 
445 
447 
448 
464 
504 


NO_ERROR 
ERROR_KBD_INVALID_HANDLE 
ERROR_KBD_FOCUS_REQUIRED 
ERROR_KBD_KEYBOARD_BUSY 
ERROR_KBD_INVALID_CODEPAGE 
ERROR_KBD_DETACHED 
ERROR_KBD_EXTENDED_SG 
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Remarks 

Keyboard code page support is not available without the DEVINFO=KBD 
statement in the CONFIG.SYS file. Refer to IBM Operating System/2.0 
Command Reference for a complete description of CODEPAGE and DEV- 


INFO. 


24 Keyboard (KBD) functions 


KbdSetCustXt (xPM) 


Description 


This call installs, on the specified handle, the translate table that this call 
points to. This translate table affects only this handle. 


4edefine INCL_KBD 
#include <os2.h> 


USHORT KbdSetCustxXt (PUSHORT usCodePage, HKBD hkbd); 


usCodePage (PUSHORT) - input 
A pointer to the translation table used to translate scan code to ASCII 
code for a specified handle. The format of the translate table is docu- 
mented in the Set Code Page IOCTL 50H. Refer to IBM Operating Sys- 
tem/2.0 Technical Library Physical Drive Device Drivers Reference for a 
complete discussion of Set Code Page IOCTL 50H. 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


O NO_ERROR 
377 ERROR_KBD_INVALID_ECHO_MASK 
378 ERROR_KBD_INVALID_INPUT_MASK 
439 ERROR_KBD_INVALID_HANDLE 
445 ERROR_KBD_FOCUS_REQUIRED 
447 ERROR_KBD_KEYBOARD_BUSY 
464 ERROR_KBD_DETACHED 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


The translate table must be maintained in the caller’s memory. No copy of 
the translate table is made by KbdSetCustxXt. KbdSetCp reverses the action 
of KbdSetCustXt and sets the handle equal to one of the system translate 
tables. If memory is dynamically allocated by the caller for the translate 
table and is freed before the KbdSetCp is performed, KbdSetCp and future 
translations might fail. 
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KbdSetFgnd (xPM) 


Description 
This call raises the priority of the foreground keyboard’s thread. 


4tdefine INCL_KBD 
#include <os2.h> 


USHORT KbdSetFgnd( void); 


Return Value 


O NO_ERROR 
447 ERROR_KBD_KEYBOARD_BUSY 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


KbdSetFgnd marks the current process that owns the keyboard. Threads in 
this process receive a priority boost. The previous foreground keyboard 
threads lose their priority boost. This function should only be issued by a 
Keyboard Subsystem during KbdCharIn or KbdStringIn processing. 
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KbdSetStatus (FAPI, xPM) 


Description 
This call sets the characteristics of the keyboard. 


4edefine INCL_KBD 
include <os2.h> 


USHORT KbdSetStatus (PKBDINFO pkbdinfo, HKBD hkbd); 


pkbdinfo (PKBDINFO) - input 
Address of the keyboard status structure: 


cb CUSHORT ) 
Length, in bytes, of this data structure, including length. 


10 Only valid value. 


fsMask (USHORT ) 
The system state altered by this call. If bits O and 1 are off, the echo 
state of the system is not altered. If bits 2 and 3 are off, the binary 
and ASCII state of the system is not altered. If bits O and 1 are on, 
or if bits 2 and 3 are on, the function returns an error. If binary 
mode is set, echo is ignored. 


Bit Description 
15-9 Reserved, set to zero. 
8 Shift return is on. 
(fsMask & KEYBOARD_SHIFT_REPORT) 
7 Length of the turnaround character (meaningful only if 
bit 6 is on). 
(fsMask & KEYBOARD _2B TURNAROUND) 
6 Turnaround character is modified. 
(fSsMask & KEYBOARD_MODIFY_TURNAROUND) 
5 Interim character flags are modified. 
(fSMask & KEYBOARD_MODIFY_INTERIM) 
4 Shift state is modified. 
(fsMask & KEYBOARD_MODIFY_STATE) 
3 ASCII mode is on. 
(fsMask & KEYBOARD_ASCII_MODE) 
2 Binary mode is on. 
(fSMask & KEYBOARD _ BINARY MODE) 


1 Echo off. 
(fsMask & ECHO_OFF) 
O Echo on. 


(fsMask & ECHO_ON) 
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chTurnAround 


(USHORT ) 


Definition of the turnaround character. In ASCII and extended- 
ASCII format, the turnaround character is defined as the carriage 
return. In ASCII format only, the turnaround character is defined 
in the low-order byte. 


fsInterim (USHORT) 
Interim character flags: 


Bit 
15-8 

7 

6 

5 
4—O 


Description 
NLS shift state. 


Interim character flag is on 


Reserved, set to zero 


Application requested immediate conversion 


Reserved, set to zero 


fsState (USHORT) 
Shift state. 


Bit 
15 
14 
13 
12 
Ll 
10 


OrFNWHOON ® O 


Description 

SysReq key down 
CapsLock key down 
NumLock key down 
scrollLock key down 
Right Alt key down 
Right Ctrl key down 
Left Alt key down 
Left Ctrl key down 
Insert on 

CapsLock on 
NumLock on 
ScrollLock on 

Either Alt key down 
Either Ctrl key down 
Left Shift key down 
Right Shift key down 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 


Return value 


NO_ERROR 
ERROR_KBD_INVALID_LENGTH 
ERROR_KBD_INVALID_ECHO_MASK 
ERROR_KBD_INVALID_INPUT_MASK 
ERROR_KBD_INVALID_HANDLE 
ERROR_KBD_FOCUS_REQUIRED 


O 
376 
377 
378 
439 
445 
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(fsState & KBDSTF_SYSREQ) 
(fsState & KBDSTF_CAPSLOCK) 
(fsState & KBDSTF_NUMLOCK) 
(fsState & KBDSTF_SCROLLLOCK) 
(fsState & KBDSTF_RIGHTALT) 
(fsState & KBDSTF_RIGHTCONTROL) 
(fsState & KBDSTF_LEFTALT) 
(fsState & KBDSTF_LEFTCONTROL) 
(fsState & KBDSTF_INSERT_ON) 
(fsState & KBDSTF_CAPSLOCK_ON) 
(fsState & KBDSTF_NUMLOCK_ON) 
(fsState & KBDSTF_SCROLLLOCK_ON) 
(fsState & KBDSTF_ALT) 

(fsState & KBDSTF_CONTROL) 
(fsState & KBDSTF_LEFTSHIFT) 
(fsState & KBDSTF_RIGHTSHIFT) 


447 ERROR_KBD_KEYBOARD_BUSY 
464 ERROR_KBD_DETACHED 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


Shift return (bit 8 in sysstate) must be disabled in ASCII mode. KbdSetStatus 
is ignored for a Vio-windowed application. 


Family API Considerations 


Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following restrictions apply to KbdSetStatus when coding in 
the DOS mode: 


KbdSetStatus does not accept a bit mask of 10 (ASCII on, Echo Off). 
Raw (binary) Mode and Echo On are not supported and return an er- 
ror if requested. 

KbdHandle is ignored. 

Interim character is not supported. 

Turnaround character is not supported. 
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KbdStringin (FAPI, xPM) 


Description 


This call reads a character string (character codes only) from the key- 
board. 


define INCL_KBD 
Finclwde <os?.h> 


USHORT KbdStringIn (PCH pch, PSTRINGINBUF pchIn, 
USHORT fsWait, HKBD hkbd); 


pch (PCH) - output 
Address of the character string buffer. 


pchiIn (PSTRINGINBUF) - input/output 
Address of the length of the character string buffer. On entry, buflen is 
the maximum length, in bytes, of the buffer. The maximum length that 


can be specified is 255. Template processing has meaning only in the 
ASCII mode. 


cb (USHORT ) 
Length of the input buffer. 


cchIn (USHORT ) 
Number of bytes read into the buffer. 


fsWait (USHORT) - input 
Wait if a character is not available. 


Value Definition 


O Wait. In Binary input mode, the requestor waits until Char- 
Buffer is full. In ASCII input mode, the requestor waits until a 
carriage return is pressed. 

(fsWait == IO_WAIT) 

1 No wait. The requestor gets an immediate return if no charac- 
ters are available. If characters are available, KbdStringIn re- 
turns immediately with as many characters as are available 
(up to the maximum). No wait is not supported in ASCII input 
mode. 

(fsWait == IO_NOWAIT) 


hkbd (HKBD) - input 
Default keyboard or the logical keyboard. 
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Return value 


O NO_ERROR 
375 ERROR_KBD_INVALID_IOWAIT 
439 ERROR_KBD_INVALID_HANDLE 
445 ERROR_KBD_FOCUS_REQUIRED 
464 ERROR_KBD_DETACHED 
504 ERROR_KBD_EXTENDED_SG 


Remarks 


The character strings may be optionally echoed on the display if echo 
mode is set. When echo is on each character is echoed as it is read from 
the keyboard. Echo mode and BINARY mode are mutually exclusive. Ref- 
erence KbdSetStatus and KbdGetStatus for more information. 


The default input mode is ASCII. In ASCII mode, 2-byte character codes only 
return in complete form. An extended ASCII code is returned in a 2-byte 
string. The first byte is ODH or EOH and the next byte is an extended code. 


In input mode (BINARY, ASCII), the following returns can be set and re- 
trieved with KbdSetStatus and KbdGetStatus: 


e Turnaround character 
e Echo mode 

e Interim character flag 
e Shift state 


The received input length is also used by the KbdStringIn line edit func- 
tions for re-displaying and entering a caller specified string. On the next 
KbdStringIn call the received input length indicates the length of the input 
buffer that may be recalled by the user using the line editing keys. A value 
of O inhibits the line editing function for the current KbdStringIn request. 


KbdStringIn completes when the handle has access to the physical key- 
board (focus), or is equal to zero and no other handle has the focus. 


Family API considerations 


Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following restrictions apply to KbdStringIn when coding in 
the DOS mode: 


° KbdHandle is ignored 


Refer to the DosRead’s “Family API considerations” for differences between 
DOS and OS/2 mode when reading from a handle opened to the CON device. 
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KodSynch (xWPM) 


Description 


This call synchronizes access from a keyboard subsystem to the keyboard 
device driver. 


Htdefine INCL KBD 
rinclude <as2.h> 


USHORT KbdSynch (USHORT fsWait) ; 


fsWait CUSHORT) - input 
Wait for the bond. Values are: 


Value Definition 
QO Indicates the requestor does not wait for access to the device 
driver. 
(fsWait == IO_WAIT) 
1 Indicates the requestor waits for access to the device driver. 
(fsWait == IO_NOWAIT) 


Return value 


O NO_ERROR 
121 ERROR_SEM_TIMEOUT 


Remarks 


KbdSynch blocks all other threads within a session until return from the sub- 
system to the router. To ensure proper synchronization, KbdSynch should be 
issued by a keyboard subsystem if it intends to issue a DosDevI0Ct1 or ac- 
cess dynamically shared data. KbdSynch does not protect globally shared 
data from threads in other sessions. 
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KbdXlate (xPM) 


Description 


This call translates scan codes with shift states into ASCII codes. 


define INCL_KBD 
Finclude <os2.h> 


USHORT KbdXlate (PKBDTRANS pkbdtrans, HKBD hkbd); 


pkbdtrans (PKBDTRANS) - input 


Address of the translation record structure: chChar, chScan, fbStatus, 
bNlsShift, fsState, time (KBDKEYINFO) character data information 
structure as defined in KbdCharIn call. 


fsDD (USHORT) 


See the KbdDDFlagWord call in the “Physical keyboard device driver” 
section of IBM OS/2 2.0 Technical Library Physical Device Driver 


Reference. 


fsXlate (USHORT) 


Translation flag: 


Value Definition 


QO Translation incomplete. 
1 ‘Translation complete. 


TSomiTt CUSHORT) 


Identifies the state of translation across 


successive calls; initially 


the value should be zero. It might take several calls to this function 
to complete a character. The value should not be changed unless a 
new translation is required (that is, reset value to zero). 


sZero (USHORT ) 


See description for fsShift. 


hkbd (HKBD) - input 


Default keyboard or the logical keyboard 


Return value 


O 
439 
445 
447 
464 
504 


NO_ERROR 
ERROR_KBD_INVALID_HANDLE 
ERROR_KBD_FOCUS_REQUIRED 
ERROR_KBD_KEYBOARD_BUSY 
ERROR_KBD_DETACHED 
ERROR_KBD_EXTENDED_SG 
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Remarks 


It might take several calls to complete a translation because of accent key 
combinations, or other complex operations. 


The fsShift and sZero are for use by the keyboard translation routines. 
These fields are reserved and must only be accessed by the caller prior 
to starting a translation sequence and then they must be set to zero. 
The KbdXlate function is intended to be used for translating a particu- 
lar scan code for a given shift state. The KbdXlate function is not in- 
tended to be a replacement for the OS/2 system keystroke translation 
function. 
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Mouse (MOU) 
functions 





This part describes the OS/2 Mouse API interface. 


For information regarding mouse device drivers, mouse pointer draw de- 
vice, mouse installation, and mouse IOCTLs, refer to IBM OS/2 2.0 Tech- 
nical Library Physical Device Drivers Reference. 


Notes 


e Calls marked xPM are not supported by Presentation Manager, and 
must not be used by Presentation Manager applications. An error 
code is returned if any of these calls are issued. 

e Calls marked xWPM are not windowable and are not supported by 
Presentation Manager. They can be used in OS/2 mode. 

e Calls marked FAPI are present in the Family API. 


Table 2-1 Mouse call list 


Function call Icon 
MouClose xPM 
MouDeRegister XWPM 
MouDrawPtr xPM 
MouFlushQue xPM 
MouGetDevStatus xPM 
MouGetEventMask xPM 
MouGetNumButtons xPM 
MouGetNumMickeys xPM 
MouGetNumQueE | xPM 
MouGetPtrPos xPM 
MouGetPtrShape xPM 
MouGetScaleFact xPM 
MoulInitReal xXWPM 
MouOpen xPM 
MouReadEventQue xPM 
MouRegister XWPM 
MouRemovePtr xPM 
MouSetDevStatus xPM 
MouSetEventMask xPM 
MouSetPtrPos xPM 
MouSetPtrShape xPM 
MouSetScaleFact xPM 
MouSynch XWPM 
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MouClose (xPM) 


Description 
This call closes the mouse device for the current session. 


4tdefine INCL_MOU 
#Finclude <os2.h> 


USHORT MouClose (HMOU hmou); 


hmou (HMOU) - input 
Mouse device handle from a previous MouOpen. 


Return value 


O 
385 
466 
501 
505 


NO_ERROR 
ERROR_MOUSE_NO_DEVICE 
ERROR_MOU_DETACHED 
ERROR_MOUSE_NO_CONSOLE 
ERROR_MOU_EXTENDED_SG 


Remarks 


MouClose closes the mouse device for the current session and removes the 
mouse device driver handle from the list of valid open mouse device handles. 
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MouDeRegister (xWPM) 


Description 


This call deregisters a mouse subsystem previously registered within a 
session. 


4tdefine INCL_MOU 
#Finclude <os2.h> 


USHORT MouDeRegister (void); 


Return value 


O 
385 
416 
466 
505 


NO_ERROR 
ERROR_MOUSE_NO_DEVICE 
ERROR_MOUSE_DEREGISTER 
ERROR_MOU_DETACHED 
ERROR_MOU_EXTENDED_SG 


Remarks 


Processes issuing MouDeRegister calls must conform to the following rules: 


e The process that issued the MouRegister must release the session 


(by a MouDeRegister) from the registered subsystem before another 
PID may issue MouRegister. 


e The process that issued the MouRegister is the only process that may 


issue MouDeRegister against the currently registered subsystem. 


e After the owning process has released the subsystem with a Mou 


DeRegister, any other process in the session may issue a MouRegis- 
ter and therefore modify the mouse support for the entire session. 
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MouDrawPtr (xPM) 


Description 


This call allows a process to notify the mouse device driver that an area 
previously restricted to the pointer image is now available to the mouse de- 
vice driver. 


#define INCL_MOU 
#Finclude <os2.h> 


USHORT MouDrawPtr (HMOU hmou); 


hmou (HMOU) - input 
Mouse device handle from a previous MouOpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


The collision area (the pointer image restricted area) is established by 
Mou0pen and by MouRemovePtr. MouDrawPtr nullifies the effect of the Mou 
RemovePtr command. If there was no previous MouDrawPtr command or if a 
previous MouDrawPtr command has already nullified the collision area, the 
MouRemovePtr command is effectively a null operation. 


This call is required to begin session pointer image drawing. Immediately 
after Mou0pen is issued, the collision area is defined as the size of the dis- 
play. A MouDrawPtr is issued to begin pointer drawing after the MouOpen. 
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MouFlushQue (xPM) 


Description 


This call directs the mouse driver to flush (empty) the mouse event queue 
and the monitor chain data for the session. 


4edefine INCL_MOU 
#Finclude <os2.h> 


USHORT MouFlushQue (HMOU hmou); 


hmou (HMOU) - input 
Mouse device handle from a previous MouOpen. 


Return value 


O 
385 
466 
501 
505 


NO_ERROR 
ERROR_MOUSE_NO_DEVICE 
ERROR_MOU_DETACHED 
ERROR_MOUSE_NO_CONSOLE 
ERROR_MOU_EXTENDED_SG 
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MouGetDevStatus (xPM) 


Description 


This call returns status flags for the installed mouse device driver. 


#tdefine INCL_MOU 
#Finclude <os2.h> 


USHORT MouGetDevStatus (PUSHORT pfsDevStatus, HMOU hmou); 


pfsDevStatus (PUSHORT) - output 
Address of the current status flag settings for the installed mouse de- 
vice driver. The return value is a 2-byte set of bit flags. 


Bit Description 
15-10 Reserved, set to zero. 


9 Set if mouse data returned in mickeys, not pels. 
(*pfsDevStatus & MOUSE_MICKEYS) 

8 Set if the drawing operations for pointer draw routine are 
disabled. 


(*pfsDevStatus & MOUSE_DISABLED) 
7-4 Reserved, set to zero. 

3 Set if pointer draw routine disabled by unsupported mode. 
(*pfsDevStatus & MOUSE_UNSUPPORTED_MODE) 

2 Set if flush in progress. 
(*pfsDevStatus & MOUSE_FLUSH) 

1 Set if block read in progress. 
(*pfsDevStatus & MOUSE_BLOCKREAD) 

O Set if event queue busy with I/O. 
(*pfsDevStatus & MOUSE_QUEUEBUSY) 


hmou (HMOU) - input 
Mouse device handle from a previous MouOpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 
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MouGetEventMask (xPM) 


Description 


This call returns the current value of the mouse event queue mask. 


d#Fdefine INCL MOU 
fHinclude <os2.h> 


USHORT MouGetEventMask (PUSHORT pfsEvents, HMOU hmou); 


pfsEvents (PUSHORT) - output | 
Address in application storage where the current mouse device driver’s 
event mask is returned to the caller by the mouse device driver. 


The EventMask is set by MouSetEventMask and has the following definition: 


Bit Description 
15-7 Reserved, set to zero. 

6 Set to report button 3 press/release events, without mouse 
motion. 
(*pfsEvents & MOUSE_BN3_DOWN) 

5 Set to report button 3 press/release events, with mouse motion. 
(*pfsEvents & MOUSE_MOTION_WITH_BN3_DOWN) 

4 Set to report button 2 press/release events, without mouse 
motion. 
(*pfsEvents & MOUSE_BN2_DOWN) 

3 Set to report button 2 press/release events, with mouse motion. 
(*pfsEvents & MOUSE_MOTION_WITH_BN2_DOWN) 

2 Set to report button 1 press/release events, without mouse 
motion. 
(*pfsEvents & MOUSE_BN1_DOWN) 

1 Set to report button 1 press/release events, with mouse motion. 
(*pfsEvents & MOUSE_MOTION_WITH_BN1_DOWN) 

O Set to report mouse motion events with no button press/release 
events. 
(*pfsEvents & MOUSE_MOTION) 


hmou (HMOU) - input 
Handle of the mouse device from a previous Mou0pen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 
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501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


Buttons are logically numbered from left to right unless the mouse has 
been configured as left-handed, in which case the buttons are numbered 


from right to left. 
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MouGetNumButtons (xPM) 


Description 


This call returns the number of buttons supported on the installed mouse 
driver. 


+#define INCL _MOU 
#include <os2.h> 


USHORT MouGetNumButtons (PUSHORT pcButtons, HMOU hmou); 


pcButtons (PUSHORT) - output 
Address of the number of physical buttons. The return values for the 
number of buttons supported are: 


Value Definition 


1 One mouse button 
2 Two mouse buttons 
3 Three mouse buttons. 


hmou (HMOU) - input 
Handle of the mouse device from a previous Mou0pen. 


Return value 


385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 

501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 
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MouGetNumMickeys (xPM) 


Description 


This call returns the number of mickeys in each centimeter for the in- 
stalled mouse driver. 


4Hdefine INCL MOU 
Finclude <os7.h> 


USHORT MouGetNumMickeys (PUSHORT pcMickeys, HMOU hmou); 


pcMickeys (PUSHORT) - output 
Address of the number of physical mouse motion units. Mouse motion 
units are reported in mickeys in each centimeter. This value is con- 
stant based upon the mouse device attached. 


hmou (HMOU) - input 
Handle of the mouse device from a previous MouOpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
5905 ERROR_MOU_EXTENDED_SG 


Mouse (MOU) functions 45 


MouGetNumQueE! (xPM) 


Description 
This call returns the current status for the mouse device driver event queue. 


4tdefine INCL_MOU 
#Finclude <os2.h> 


USHORT MouGetNumQueE! (PMOUQUEINFO qmougi, HMOU hmou) ; 


qmouqi (PMOUQUEINFO) - output 
Address of the mouse queue status structure: 


cEvents (USHORT) 
Current number of event queue elements, in the range 0 <> value 
<> maxnumgaelements. 


cMaxEvents (USHORT) 
Maximum number of queue elements as specified in the QSIZE = NN 
parameter in DEVICE=MOUSExxx.SYS statement in CONFIG.SYS. 


hmou (HMOU) - input 
Contains the handle of the mouse device obtained from a previous 
MouQpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 
5901 ERROR_MOUSE_NO_CONSOLE 
5905 ERROR_MOU_EXTENDED_SG 


Remarks 


The maxnumgelements returned by this function is established during 
mouse device driver configuration. See the mouse DEVICE=MOUSExxx.SYS 
statement in the IBM OS/2 2.0 Command Reference for further details. 
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MouGetPtrPos (xPM) 


Description 


This call queries the mouse driver to determine the current row and col- 
umn coordinate position of the mouse pointer. 


define INCL_MOU 
Finclude <osz,h> 


USHORT MouGetPtrPos (PPTRLOC pmouLoc, HMOU hmou); 


pMouLoc (PPTRLOC) - output 
Address of the mouse pointer position structure: 


row (USHORT ) 
Current pointer row coordinate (pels or characters). 


col (USHORT ) 
Current pointer column coordinate (pels or characters). 


hmou (HMOU) - input 
Contains the handle of the mouse device obtained from a previous 
MouQpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


For a text window (VIO) application, the text window is a view on the larger 
logical video buffer (LVB). The mouse pointer can be outside that view and 
still be within the extent of the LVB. MouGetPtrPos then returns the coor- 
dinates of the cell under the mouse pointer. If the pointer is outside the 
LVB image extent, the coordinates of the nearest LVB cell are returned. In 
either case, the LVB is scrolled until the reported LVB cell appears within 
the view window. 


Mouse (MOU) functions 47 


MouGetPtrShape (xPM) 


Description 


This call allows a process to get (copy) the pointer shape for the session. 


4tdefine INCL MOU 
4tinclude <os2.h> 


USHORT MouGetPtrShape (PBYTE pBuf, PPTRSHAPE pmoupsInfo, HMOU hmou) ; 


pBuf (PBYTE) - output 
Address of an area in application storage where the pointer draw de- 
vice driver returns the pointer bit image. See MouSetPtrShape for a fur- 
ther description of the resulting content of this buffer. 


pmoupsInfo (PPTRSHAPE) - input/output 
Address of a structure in application storage where the application 
stores the data necessary for the pointer device driver to return infor- 
mation about the Row by Col image for each bit plane for the mode the 
display is currently running. See MouSetPtrShape for a further descrip- 
tion of the contents of this structure. 


cb (USHORT) 
Length of the pointer buffer available for the pointer device driver 
to build a Row by Col image for each bit plane for the mode the dis- 
play is currently running. This value is supplied by the application. 
If the value is too small, pointer draw places the true length of the 
image in this field, and returns an error. 


For all OS/2 system-supported modes, TotLength is specified in 
bytes and is equal to: 
Mono & text modes 
For text mode height and width must be 1, so length is always 4. 
cb (height in chars) « (width in chars) * 2 * 2 
Ll*l*2*2 
4 


Graphics mode 
Width-in-pels must be a multiple of 8. 
cb = (height in pels)+(width in pels)«(bits per pel)*2/8 


Modes 4 and 5 (320 x 200) 
cb = (height) + (width) *2*2/8 
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Mode 6 (640 x 200) 
cb = (height) + (width) + 1+*2/ 8 


Length calculations produce byte boundary buffer sizes. 


col (USHORT) 
Number of columns in the mouse shape. In graphics modes, this 
field contains the pel width (columns) of the mouse shape for the 
session and must be greater than or equal to 1. In text modes, col 
must equal 1. 


row (USHORT ) 
Number of rows in the mouse shape. In graphics modes, this field 
contains the pel height (rows) of the mouse shape for the session 
and must be greater than or equal to 1. In text modes, row must 
equal 1. 


colHot (USHORT) 
This value is returned by the mouse device driver to indicate the 
relative column offset within the pointer image. The value defines 
the center (hotspot) of the pointer image. This value is a signed 
number that represents either character or pel offset, depending 
on the display mode. 


rowHot (USHORT) 
This value is returned by the mouse device driver to indicate the 
relative row offset within the pointer image. The value defines the 
center (hotspot) of the pointer image. This value is a signed num- 
ber that represents either character or pel offset, depending on the 
display mode. 


hmou (HMOU) - input 


Handle of the mouse device from a previous MouOpen. 


Return value 


O 
385 
387 
466 
501 
505 


NO_ERROR 
ERROR_MOUSE_NO_DEVICE 
ERROR_MOUSE_INV_PARMS 
ERROR_MOU_DETACHED 
ERROR_MOUSE_NO_CONSOLE 
ERROR_MOU_EXTENDED_SG 


Remarks 


The 


application passes a parameter list with the same meaning as defined 


for MouSetPtrShape to the mouse device driver. The mouse device driver 
copies the parameters that describe the pointer shape and attributes into 
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the pointer definition control block pointed to by the PtrDefRec parameter. 
The word O (buffer length = cb) pointer definition record parameter field 
must contain the size in bytes of the application buffer where the device 
driver is to insert the sessions pointer image. All other words in the pa- 
rameter list are returned to the application by MouGetPtrShape. 


If the buffer size is insufficient, the TotLength field contains the actual size 
in bytes of the returned pointer image. 


The pointer shape may be set by the application with MouSetPtrShape or 
may be the default image provided by the installed Pointer Device Driver. 
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MouGetScaleFact (xPM) 


Description 


This call returns a pair of 1-word scaling factors for the current mouse device. 


define INCL _MOU 
4Finclude <os2.h> 


USHORT MouGetScaleFact (PSCALEFACT pmouscFactors, HMOQU hmou) ; 


pmouscFactors (PSCALEFACT) - output 
Address of the control block structure that contains the current row 
and column coordinate scaling factors. The scaling factors must be 
greater than or equal to 1 and less than or equal to (32K — 1). 


rowScale (USHORT ) 
Row scaling factor. 


colScale (USHORT ) 
Column scaling factor. See MouSetScaleFact for more information. 


hmou (HMOU) - input 
Contains the handle of the mouse device obtained from a previous 
MouQpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


The units of the scale factor depend on the mode of the display screen for 
the session. If the screen is operating in text mode, the scaling units are 
relative to characters. If the screen is operating in graphics mode, the scal- 
ing units are relative to pels. 
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MoutnitReal (xWPM) 


Description 


This call initializes mouse pointer draw support for DOS mode. 


4tdefine INCL_MOU 
#include <os2.h> 


USHORT MouInitReal (PSZ driverName); 


driverName (PSZ) - input 
Address of the name of the Pointer Draw Device Driver used as the 
pointer-image drawing routine for the DOS mode session. 


The name of the device driver must be included in the CONFIG.SYS file 
at system start-up time. 


If the selector portion of the far address is zero and the offset portion is 
non-zero, the offset portion identifies the power-up display configuration. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
466 ERROR_MOU_DETACHED 
412 ERROR_MOUSE_SMG_ONLY 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


MouInitReal is issued by the Base Video Subsystem at system initializa- 
tion time. 


The DOS mode mouse API (INT 33H), in contrast to the OS/2 mode Mouse 
API, does not contain an OPEN command. In addition, there is only one 
session for DOS mode. 


The default pointer draw routine for DOS mode is located in the same 
pointer draw device driver, POINTERS, that is used for OS/2 mode. Es- 
tablishing addressability to the pointer draw routine must be done during 
system initialization. This requires passing the entry point of the DOS 
mode pointer draw routine to the mouse device driver. This is the purpose 
of the MoulInitReal call. It passes the address of the default, power-up 
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pointer draw routine for DOS mode to the mouse device driver. This ini- 
tialization is transparent to applications. 


This call is for use only by the Base Video Subsystem when invoked dur- 
ing system initialization under the shell/session manager PID. 


The error code ERROR_MOUSE_SMG_ONLY is valid from shell process only. 
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MouOpen (xPM) 


Description 


This call opens the mouse device for the current session. 


4tdefine INCL_MOU 
#include <os2.h> 


USHORT MouOpen (PSZ pszDvrName, PHMOU phmou) ; 


pszDvrName (PSZ) - input 
DriverName is a far pointer to an ASCIIZ string in application storage 
containing the name of the pointer draw device driver to be used as the 
pointer-image drawing routine for this session. 


The name of the device driver must be included in the CONFIG.SYS file 
at system start-up time. Applications that use the default pointer draw 
device driver supplied by the system must push a double-word of Os in 
place of an address. 


DriverName has a different definition when the caller is the Base Video 
Subsystem (BVS). In this case the selector portion of the far address is 
zero. The offset portion is non-zero and contains a display configura- 
tion number (sequentially numbered where 1 is the first display con- 
figuration). The Mou0pen call issued by BVS is executed on the 
VioSetMode path. Using the display configuration number passed on 
the MouOpen call, the Base Mouse Subsystem can detect a change in 
display configurations. This form of the Mou0pen call is not recom- 
mended for applications. Applications should either push the far ad- 
dress of an ASCIJZ pointer draw device driver name or push two words 
of zeros. 


phmou (PHMOU) - output 
Address of a 1-word value that represents the mouse handle returned 
to the application. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
390 ERROR_MOUSE_INV_MODULE_PT 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 
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Remarks 


MouOpen initializes the Mouse functions to a known state. The application 
may have to issue additional mouse functions to establish the environment 
it desires. For example, after the MouOpen, the collision area is defined to be 
the size of the entire display. Therefore, to get the pointer to be displayed, 
the application must issue a MouDrawPtr to remove the collision area. 


The state of the mouse after the first Mou0pen is: 


Row/Col scale factors set to 16/8. (See MouSetScaleFact.) 

All events reported. (See MouSetEventMask.) 

Empty event queue. (See MouReadEventQue and MouGetNumQueE1.) 

All user settable Device Status bits reset. (Set to zero. See MouSetDev 

Status.) 

e Pointer set to center of screen if valid display mode is set. (See 
MouSetPtrPos.) 

e Pointer shape set to the default for the pointer device driver currently 
registered in the session. (See MouSetPtrShape.) 

e Collision area equal to full screen. (See MouDrawPtr and MouRemovePtr.) 
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MouReadEventQue (xPM) 


Description 


This call reads an event from the mouse device FIFO event queue, and 
places it in a structure provided by the application. 


4tdefine INCL_MOU 
4#FAinclude <os2.h> 


USHORT MouReadEventQue (PMOUEVENTINFO pmouevEvent, PUSHORT pfWait, 


HMOU hmou); 


pmouevEvent (PMQUEVENTINFQ) - output 
Address of the status of the mouse event queue. 


fs (USHORT ) 
State of the mouse at the time of the event. 


Bit 
15-7 
6 


Description 

Reserved, set to zero. 

Set to report button 3 press/release events, without mouse 
motion. 

(fs & MOUSE_BN3_DOWN) 

Set to report button 3 press/release events, with mouse 
motion. 

(fs & MOUSE_MOTION_WITH_BN3_DOWN) 

Set to report button 2 press/release events, without mouse 
motion. 

(fs & MOUSE_BN2_DOWN) 

Set to report button 2 press/release events, with mouse 
motion. 

(fs & MOUSE_MOTION_WITH_BN2_DOWN) 

Set to report button 1 press/release events, without mouse 
motion. 

(fs & MOUSE_BN1_DOWN) 

Set to report button 1 press/release events, with mouse 
motion. 

(fs & MOUSE_MOTION_WITH_BN1_DOWN) 

Set to report mouse motion events with no button press/ 
release events. 

(fs & MOUSE_MOTION) 


time (ULONG) 
Time stamp (in milliseconds) since the system was started. 


row (USHORT ) 
Absolute or relative row position. 
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col (USHORT ) 
Absolute or relative column position. 


pfWait (PUSHORT) - input 
Address of the action to take when MouReadEventQue is issued and 
the mouse event queue is empty. If the mouse event queue is not 
empty, this parameter is not examined by the mouse support. Read- 
Type values are: 


Value Definition 


O No Wait for data on empty queue (return a NULL record) 
(*pfWait == MOU_WAIT) 

1 WAIT for data on empty queue. 
(*pfWait == MOU_NOWAIT) 


hmou (HMOU) - input 
Handle of the mouse device from a previous MouOpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
387 ERROR_MOUSE_INV_PARMS 
393 ERROR_MOUSE_NO_DATA 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


The types of queued events are directly affected by the current value of the 
Mouse EventMask. MouSetEventMask is used to indicate the types of events de- 
sired, and MouGetEventMask is used to query the current value of the mask. 
Refer to these functions for further explanation of the masking of events. 


Recognition of the mouse transition depends on the use of MouState re- 
turned in the event record. The application should focus on bit transitions 
that occur in this word. It is important to properly set the event mask with 
MouSetEventMask for reporting the state transitions. 


MouState reports the state of the mouse that resulted from the action that 
caused the event. The action can be pressing or releasing a button, and/or 
moving the mouse. All status is given, regardless of the EventMask that was 
used to determine whether or not to report the event. 


For example, assume the EventMask indicates that the application wants 
only button 1 event. The EventMask has only bits 1 and 2 set in this case. 
Also assume the current state of the mouse is no buttons down, and 
mouse is not moving. At this point, button 1 is pressed causing an event; 
the status shows button 1 down (bit 2 set). Next the mouse is moved, 
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thereby causing more events; status shows bit 1 set. Finally, mouse is 
stopped and button 1 is released. The event shows status with no bits set. 
Next, button 2 is pressed. No event occurs. Mouse is then moved; again, no 
event. Then, while mouse is still in motion, button 1 is pressed; an event is 
generated with bits 1 and 3 set in the state word. While mouse is still in mo- 
tion, both buttons are released. Because button 1 changes states, an event 
occurs. The state word has bit O set. Finally, mouse is stopped. No event oc- 
curs, again because no button 1 transition has taken place. 


Note We have found that the mouse queue does not, in fact, behave as 
described above by IBM. Our tests have been in OS/2 2.0 + Service Pack. 
These quirks might be corrected in a future revision. Specifically, we have 
found the following differences: 


e If events for button 3 are enabled but movement events are dis- 
abled and the mouse has only 2 buttons, movement events will still 
be queued. 

e If, for example, button 1 is enabled, and button 2 is disabled, the 
button 2 state will be reported as up on a button 1 press irrespective 
of whether it is actually up or down. If a button 1 down-and-moving 
event occurs, thereafter, for the duration of the button 1 press, but- 
ton 2 events will be reported. 


As such, we recommend that mouse button events not be masked out us- 
ing the EventMask. Rather, all events for all existing buttons should be ac- 
cepted and, if necessary, filtered by the application. 


The Row and Column fields in the Buffer parameter may contain either ab- 
solute display coordinates or relative mouse motion in mickeys. See 
MouSetDevStatus for additional information. 
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Description 
This call registers a mouse subsystem within a session. 


define INCL MOU 
#Finclude <os2.h> 


USHORT MouRegister (PSZ pszModName, PSZ pszEntryName, ULONG flFuns); 


pszModName (PSZ) - input 
Address of the dynamic link module name. The maximum length is 9 
bytes (including ASCIIZ terminator). 


pszEntryName (PSZ) - input 
Address of the dynamic link entry point name of a routine that receives 
control when any of the registered functions are called. The maximum 
length is 33 bytes (including ASCIIZ terminator). 


flFuns (ULONG) - input 
A mask of bits, where each bit set to 1 identifies a mouse function be- 


ing registered. Bit values are 


Bit 
31-22 
20 
19 
18 
17 
16 
15 
14 
13 
12 
11 
10 


OrFNWHOILON © O 
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Registered function Mask 


Reserved, set to zero 


MouSetDevStatus 
MoulInitReal 
MouSetPtrPos 
MouGetPtrPos 
MouRemovePtr 
MouDrawPtr 
MouSetPtrShape 
MouGetPtrShape 
MouClose 
MouOpen 
Reserved 
Reserved 
MouSetEventMask 
MouSetScaleFact 
MouGetEventMask 
MouGetScaleFact 
MouReadEventQue 
MouGetNumQueeE | 
MouGetDevStatus 
MouGetNumMickeys 
MouGetNumButtons 


(lFuns & MR MOUSETDEVSTATUS) 
(flFuns & MR_MOUINITREAL) 
(flFuns & MR_MOUSETPTRPOS) 
(flFuns & MR_MOUGETPTRPOS) 
(flFuns & MR MOUREMOVEPTR) 
(lFuns & MR-MOUDRAWPTR) 
(lFuns & MR_MOUSETPTRSHAPE) 
(flFuns & MR_MOUGETPTRSHAPE) 
(flFuns & MR_MOUCLOSE) 

(flFuns & MR_MOUOPEN) 


(flFuns & MR_-MOUSETEVENTMASK) 
(flFuns & MR_MOUSETSCALEFACT) 
(flFuns & MR-MOUGETEVENTMASK) 
(flFuns & MR_-MOUGETSCALEFACT) 
(flFuns & MR_-MOUREADEVENTQUE) 
(f[Funs & MR_-MOUGETNUMQUEEL) 
(f[Funs & MR_-MOUGETDEVSTATUS) 
(flFuns & MR_-MOUGETNUMMICKEYS) 
(flFuns & MR MOUGETNUMBUTTONS) 
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Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
413 ERROR_MOUSE_INVALID_ASCIIZ 
414 ERROR_MOUSE_INVALID_MASK 
415 ERROR_MOUSE_REGISTER 
466 ERROR_MOU_DETACHED 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


The Base Mouse Subsystem is the default mouse subsystem. There can be 
only one MouRegister outstanding for each session without an intervening 
MouDeRegister. MouDeRegister must be issued by the same process that is- 
sued MouRegister. 


When any registered function is called, control is routed to EntryName. 
When this routine is entered, four additional values are pushed onto 
the stack. The first is the index number (Word) of the function being 
called. The second is a near pointer (Word). The third is the caller’s DS 
register (Word). The fourth is the return address (DWord) to the mouse 
router. For example, if MouGetNumMickeys were called and control routed 
to EntryName, the stack would appear as if the following instructions 
were executed: 


PUSH@ WORD NumberOfMickeys 

PUSH WORD DeviceHandle 

CALL FAR MouGetNumMickeys 

PUSH WORD Function Code 

CALL NEAR Entry point in Mouse Router 
PUSH DS 

CALL FAR EntryName 


When a registered function returns to the Mouse Router, AX is interpreted 
as follows: 


AX =0 

No error. Do not invoke the Base Mouse Subsystem routine. Return 
AX = 0. 

AX = =-1 


Invoke the BaseMouse Subsystem routine. Return AX = return code 
from the Base Mouse Subsystem. © 


AX = error (if not O or -1) 
Do not invoke the Base Mouse Subsystem Routine. Return AX = error. 
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When the mouse router receives a mouse call, it routes it to the Base 
Mouse Subsystem unless an application or other mouse subsystem has 
previously issued MouRegister for that call. If the call was registered, the 
subsystem is entered at the EntryName specified, and provided with the ap- 
plicable function code. 


The registered function mask is used to determine whether a requested 
function is performed by the registered mouse subsystem or default to the 
Base Mouse Subsystem. 


The following list shows the relationship of the mouse API calls and the 
function code passed to either the Base Mouse Subsystem or a registered 
mouse subsystem. 


MOU API calls Function code 


MouGetNumButtons OOH 
MouGetNumMickeys O1H 
MouGetDevStatus 02H 
MouGetNumQueE | 03H 
MouReadEventQue O3H 
MouGetScaleFact O5H 
MouGetEventMask O6H 
MouSetScaleFact O7H 
MouSetEventMask O8H 
Reserved 09H 
Reserved OAH 
MouQpen OBH 
MouClose OCH 
MouGetPtrShape ODH 
MouSetPtrShape OEH 
MouDrawPtr OFH 
MouRemovePtr 10H 
MouGetPtrPos 11H 
MouSetPtrPos 12H 
MoulnitReal 13H 
MouFlushQue 14H 
MouSetDevStatus 15H 


A registered mouse subsystem must leave the stack, on exit, in the exact 
state it was received. 
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MouRemovePtr (xPM) 


Description 


This call allows a process to notify the mouse device driver that the area 
defined by the passed parameters is for the exclusive use of the applica- 
tion. This area is defined as the collision area and is not available to the 
mouse device driver when drawing pointer images. 


+#define INCL_MOU 
fHinclude <os2.h> 


USHORT MouRemovePtr (PNOPTRRECT pmourtRect, HMOU hmou) ; 


pmourtRect (PNOPTRRECT) - input 
Address of the pointer shape collision area structure: 


row (USHORT) 
Upper left row coordinate (pels or characters). 


col (USHORT) 
Upper left column coordinate (pels or characters). 


CRow (USHORT ) 
Lower right row coordinate (pels or characters). 


cCol (USHORT) 
Lower right column coordinate (pels or characters). 


hmou (HMOU) - input 
Handle of the mouse device from a previous MouOpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
387 ERROR_MOUSE_INV_PARMS 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


MouRemovePtr may be issued by any process in the session. However, only 
one collision area is active at a time. Each MouRemovePtr command has the 
effect of resetting the collision area to the location and area specified by 
the current command. 
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If the logical pointer position is outside of the collision area specified by the 
latest MouRemovePtr command, the pointer image is drawn. 


The MouDrawPtr command effectively cancels the MouRemovePtr command 
and allows the pointer to be drawn anywhere on the screen, until a new 
MouRemovePtr command is issued. 
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MouSetDevStatus (xPM) 


Description 


This call sets the mouse device driver status flags for the installed mouse 
device driver. 


dedefine INCL_MOU 
include <os2.h> 


USHORT MouSetDevStatus (PUSHORT pfsDevStatus, HMOU hmou) ; 


pfsDevStatus (PUSHORT) - input 
Address of the desired status flag settings. 


The passed parameter is a 2-byte set of flags. Only the high-order byte 
has meaning. 


Bit Description 
15-10 Reserved, set to zero. 


9 Set if mouse device is to return data in mickeys. 
(*pfsDevStatus & MOUSE_MICKEYS) 
8 Set if the drawing operations for the pointer draw routine are 


to be disabled. 
(*pfsDevStatus & MOUSE_DISABLED) 
7—O Reserved, set to zero. 


hmou (HMOQU) - input 
Handle of the mouse device from a previous MouOpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
387 ERROR_MOUSE_INV_PARMS 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


MouSetDevStatus is the complement to MouGetDevStatus. However, not all 
status flags may be set with MouSetDevStatus. Only the flags correspond- 
ing to the following functions may be modified: 


e Return data in mickeys. Normally, mouse data is returned to the ap- 
plication with the absolute display mode coordinates of the pointer im- 
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age position on the display screen. By setting this status flag, mouse 
data is returned in relative mickeys, a unit of mouse movement. 
Don’t call pointer draw device. Normally, the pointer draw device 
driver is called for all drawing operations. By setting this status flag, 
the mouse device driver does not call the pointer draw device driver. 
The application must draw any required pointer image on the 
screen. 
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MouSetEventMask (xPM) 


Description 


This call assigns a new event mask to the current mouse device driver. 


##define INCL MOU 
#Finclude <os2.h> 


USHORT MouSetEventMask (PUSHORT pfsEvents, HMOU hmou); 


pfsEvents (PUSHORT) - input 
Address of a value in application storage used to indicate what mouse 
events are to be placed on the event queue (See MouReadEventQue) and 
which events are to be ignored. 


The EventMask bit values are described here: 


Bit 
15-7 
6 


Description 


Reserved, set to zero. 

Set to report button 3 press/release events, without mouse 
motion. 

(*pfsEvents & MOUSE_BN3_DOWN) 

Set to report button 3 press/release events, with mouse motion. 
(*pfsEvents & MOUSE_MOTION_WITH_BN3_DOWN) 

Set to report button 2 press/release events, without mouse 
motion. 

(*pfsEvents & MOUSE_BN2_ DOWN) 

Set to report button 2 press/release events, with mouse motion. 
(*pfsEvents & MOUSE_MOTION_WITH_BN2_DOWN) 

Set to report button 1 press/release events, without mouse 
motion. 

(*pfsEvents & MOUSE_BN1_DOWN) 

Set to report button 1 press/release events, with mouse motion. 
(*pfsEvents & MOUSE_MOTION_WITH_BN1_DOWN) 

Set to report mouse motion events with no button press/release 
events. 

(*pfsEvents & MOUSE_MOTION) 


A bit clear setting (set to zero) in an EventMask bit position indicates 
that the associated type of event is not reported to the application. Note 
also that the mouse buttons are numbered from left to right for a right- 
handed mouse and right to left for a left-handed mouse. When the mouse 
is properly positioned for use, the forefinger button is button 1. 
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hmou (HMOU) - input 
Handle of the mouse device from a previous MouOpen. 


Return value 


O 
385 
466 
501 
505 


NO_ERROR 
ERROR_MOUSE_NO_DEVICE 
ERROR_MOU_DETACHED 
ERROR_MOUSE_NO_CONSOLE 
ERROR_MOU_EXTENDED_SG 


Remarks 


Setting a bit in the event mask means that the associated event is reported 
on the mouse FIFO event queue. See MouReadEventQue for examples of 
event mask use. 
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MouSetPtrPos (xPM) 


Description 


This call directs the mouse driver to set a new row and column coordinate 
position for the mouse pointer. 


4edefine INCL_MOU 
#Finclude <os2.h> 


USHORT MouSetPtrPos (PPTRLOC pmouLoc, HMOU hmou) ; 


pmouLoc (PPTRLOC) - input 
Address of the mouse pointer position structure: 


row (USHORT ) 
New pointer row coordinate (pels or characters). 


col (USHORT) 
New pointer column coordinate (pels or characters). 


hmou (HMOU) - input 
Handle of the mouse device from a previous MouOpen. 


Return value 


O NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
387 ERROR_MOUSE_INV_PARMS 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


The application must ensure that the coordinate position specified con- 
forms to the current display mode orientation for the session. Pel values 
must be used for graphics modes and character values for text modes. 


This function has no effect on the display’s current collision area definition 
as specified by the MouDrawPtr call. If the mouse pointer image is directed 
into a defined collision area, the pointer image is not drawn until either the 
pointer is moved outside the collision area or the collision area is released 
by the MouDrawPtr call. 
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MouSetPtrShape (xPM) 


Description 


This call allows a process to set the pointer shape and size to be used as 
the mouse device driver pointer image for all applications in a session. 


4tdefine INCL_MOU 
#include <os2.h> 


USHORT MouSetPtrShape (PBYTE pBuf, PPTRSHAPE pmoupsInfo, HMOU hmou) ; 


pBuf (PBYTE) - input 
Address of a buffer containing the bit image used by the mouse device 
driver as the pointer shape for that session. The buffer consists of AND 
and XOR pointer masks in a format meaningful to the pointer draw de- 
vice driver. 


For CGA compatible text modes (0, 1, 2, and 3) the following describes 
the AND and XOR pointer mask bit definitions for each character cell 
of the masks. Bit values are 


Bit Description 
15 Blinking 
14-12 Background color 
11 Intensity 
10-8 Foreground color 
7-O Character 


pmoupsInfo (PPTRSHAPE) - input 
Address of the structure where the application stores the necessary 
data for the pointer draw device driver to build a row-by-column image 
for each bit plane for the current display mode. The pointer definition 
record structure follows: 


cp CUSnURT) 
Length of the pointer buffer available for the pointer device driver 
to build a Row by Col image for each bit plane for the mode the dis- 
play is currently running. This value is supplied by the application. 
If the value is too small, pointer draw places the true length of the 
image in this field, and returns an error. 


For all OS/2 system-supported modes, TotLength is specified in 
bytes and is equal to 
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Mono & Text Modes 
For text mode height and width must be 1, so length is always 4. 
cb (height in chars) * (width in chars) * 2 * 2 

le l*2*2 

4 


Graphics mode 
Width-in-pels must be a multiple of 8. 
cb = (height in pels)*(width in pels)«(bits per pel)*2/8 


Modes 4 and 5 (320 x 200) 
cb = (height) + (width)*2*2/8 


Mode 6 (640 x 200) 
cb = (height) + (width)*1*2/8 


Length calculations produce byte boundary buffer sizes. 


Number of columns in the mouse shape. In graphics modes, this field 
contains the pel width (columns) of the mouse shape for the session and 
must be greater than or equal to 1. In text modes, col must equal 1. 


row (USHORT ) 
Number of rows in the mouse shape. In graphics modes, this field 
contains the pel height (rows) of the mouse shape for the session and 
must be greater than or equal to 1. In text modes, row must equal 1. 


colHot (USHORT ) 
This value is returned by the mouse device driver to indicate the rel- 
ative column offset within the pointer image. The value defines the 
center (hotspot) of the pointer image. This value is a signed number 
that represents either character or pel offset, depending on the dis- 
play mode. 


rowHot (USHORT ) 
This value is returned by the mouse device driver to indicate the rel- 
ative row offset within the pointer image. The value defines the center 
(hotspot) of the pointer image. This value is a signed number that rep- 
resents either character or pel offset, depending on the display mode. 


Note For other custom displays and for the extended modes of 
the EGA attachment, it is possible to set the display to modes that 
require multiple bit planes. In these cases, the area sized by the 
row and column limits must be repeated for each bit plane sup- 
ported in that mode. Consequently, the calling process must sup- 
ply enough data to allow the mouse device driver to draw the 
pointer shape on all currently supported bit planes in that session. 
For text modes, row and column offset must equal 0. 
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hmou (HMOU) - input 
Contains the handle of the mouse device obtained from a previous 
MouQpen. 


Return value 


QO NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
387 ERROR_MOUSE_INV_PARMS 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


An application passes a data image to the mouse device driver that the 
mouse driver applies to the screen whenever the logical pointer position is 
not located in the application-defined collision area. The application syn- 
chronizes use of the screen with the mouse driver by way of MouRemovePtr 
and MouDrawPtr. 


The pointer shape is dependent on the display device driver used to sup- 
port the display device. OS/2 supports text and graphics modes. These 
modes are restricted to modes O through 7, depending on the display de- 
vice. Character modes (modes 0, 1, 2, 3, and 7) support the pointer cursor 
only as a reverse block character. This reverse block character has a char- 
acter height and width equal to 1. 


The pointer shape is mapped by the Pointer Draw Device Driver and de- 
termined completely by the application. The height and width may vary 
from 1 through the pel size of the display screen. For restrictions concern- 
ing the Pointer Draw Device Driver, see IBM Operating System/2.0 Techni- 
cal Library Physical Device Driver Reference. 
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MouSetScaleFact (xPM) 


Description 


This call assigns to the current mouse device driver a new pair of 1-word 
scaling factors. 


USHORT MouSetScaleFact (PSCALEFACT pmouscFactors, HMOU hmou) ; 


pmouscFactors (PSCALEFACT) - input 
Address of the control block structure that contains the current row 
and column coordinate scaling factors. The scaling factors must be 
greater than or equal to 1 and less than or equal to (32K — 1). 


rowScale (USHORT) 
Row scaling factor. 


colScale (USHORT) 
Column scaling factor. 


hmou (HMOU) - input 
Handle of the mouse device from a previous MouO0pen. 


Return value 


QO NO_ERROR 
385 ERROR_MOUSE_NO_DEVICE 
387 ERROR_MOUSE_INV_PARMS 
466 ERROR_MOU_DETACHED 
501 ERROR_MOUSE_NO_CONSOLE 
505 ERROR_MOU_EXTENDED_SG 


Remarks 


MouSetScaleFact sets the mickey-to-pixel ratio for mouse motion. The row 
scale and column scale ratios specify a number of mickeys for each 8 pix- 
els. The default value for the row scale is 16 mickeys for each 8 pixels. The 
default value for the column scale is 8 mickeys to 8 pixels. 


The number of pixels moved does not have to correspond 1-to-1 with the 
number of mickeys the mouse moves. The scaling factor defines a sensi- 
tivity for the mouse that is a ratio of the number of mickeys required to 
move the cursor 8 pixels on the screen. The sensitivity determines at what 
rate the cursor moves on the screen. 
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Mousynch (xWPM) 
Description 


This call provides synchronous access for a mouse subsystem to the 
mouse device driver. 


USHORT MouSynch(USHORT ioWait); 


joWait CUSHORT) - input 
Wait for access. The flag Word is defined as follows: 


Value Definition 


O Control immediately returned to requestor. 
1 Requestor waits until mouse device driver is free. 


Return value 


O NO_ERROR 
121 ERROR_SEM_TIMEOUT 


Remarks 


MouSynch blocks all other threads within a session until the semaphore 
clears (returns from the subsystem to the router). To ensure proper syn- 
chronization, MouSynch should be issued by a mouse subsystem if it in- 
tends to access dynamically modifiable shared data for each session or if 
it intends to issue a DosDevIOCtl. MouSynch does not protect globally 
shared data from threads in other sessions. 
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Video (VIO) 
functions 


This part describes the OS/2 Video API interface. 


If ERROR_VIO_SEE_ERROR_LOG is returned, further information about 
the error that occurred can be obtained by calling WinGetLastError. 


Notes 


e Calls marked xPM are not supported by Presentation Manager, and 
must not be used by Presentation Manager applications. An error 
code is returned if any of these calls are issued. 

e Calls marked xWPM are not windowable and are not supported by 
Presentation Manager. They can be used in OS/2 mode. 

e Calls marked FAPI are present in the Family API. 
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Table 3-1 Video call list 


Function call Icon 
VioDeRegister XWPM 
VioGetConfig FAPI 
VioGetCurPos FAPI 
VioGetCurType FAPI 
VioGetFont FAPI xWPM 
VioGetMode FAPI xPM 
VioGetPhysBuf FAPI xWPM 
VioGetState FAPI xWPM 
VioModeUndo xXWPM 
VioModeWait XWPM 
VioPrtSc xWPM 
VioPrtScToggle xXWPM 
VioReadCel1Str FAPI 
VioReadCharStr FAPI 
VioRegister xWPM 
VioSavRedrawUndo xXWPM 
VioSavRedrawWait xXWPM 
VioScrLock FAPI xWPM 
VioScrol1Dn FAPI 
Viescroal! Lt FAPI 
VioScrollRt FAPI 
VioScrollUp FAPI 
VioScrUnLock FAPI xWPM 
VioSetCurPos FAPI 
VioSetCurType FAPI 
VioSetFont FAPI xWPM 
VioSetMode FAPI xPM 
VioSetState FAPI xWPM 


VioWrtCel|lStr 
VioWrtCharStr 
VioWrtCharStrAtt 
VioWrtNAttr 
VioWrtNCel | 
VioWrtNChar 
VioWrtTTy 


FAPI 
FAPI 
FAPI 
FAPI 
FAPI 
FAPI 
FAPI 
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VioDeRegister (xWPM) 


Description 


This call deregisters a video subsystem previously registered within a 
session. 


Htdefine INCL_VIO 
4Hinclude <os2.h> 


USHORT VioDeRegister (void); 


Return value 


O NO_ERROR 
404 ERROR_VIO_DEREGISTER 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
465 ERROR_VIO_DETACHED 
494 ERROR_VIO_EXTENDED_SG 


Remarks 


VioDeRegister must be issued by the same process that issued the previ- 
ous VioRegister. After VioDeRegister is issued, subsequent video calls are 
processed by the Base Video Subsystem. 
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VioEndPopUp (xPM) 


Description 


This call is issued by the application when it no longer requires the tem- 
porary screen obtained through a previous VioPopUp call. 


define INCL_VIO 
+#include <os2.h> 


USHORT VioEndPopUp (HVIO hvio); 


hvio (HVIO) - input 
A reserved word of Os. 


Return value 


O NO_ERROR 
405 ERROR_VIO_NO_POPUP 
436 ERROR_VIO_INVALID_HANDLE 


Remarks 


When the application issues a VioEndPopUp call, all video calls are directed 
to the application’s normal video buffer. 


PM considerations 


An error is returned if issued with a non-zero handle. 
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VioGetAnsi (xPM) 


Description 
This call returns the current ANSI status On/Off state. 


4edefine INCL_VIO 
4FAinclude <os2.h> 


USHORT VioGetAnsi (PUSHORT pfAnsi, HVIO hvio); 


pfAnsi (PUSHORT) - output 
Address of the current ANSI status. A value of 1 indicates ANSI is ac- 
tive, and a value of O indicates ANSI is not active. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
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VioGetBuf (FAPI) 


Description 
This call returns the address of the logical video buffer (LVB). 


#define INCL_VIO 
+#include <os2.h> 


USHORT VioGetBuf (PULONG pLVB, PUSHORT pcbLVB, HVIO hvio); 


pLVB (PULONG) - output 
Address of the selector and offset of the logical video buffer. Applica- 
tions should not assume the offset portion of this far address is O. 


pcbLVB (PUSHORT) - output 
Address of the length buffer in bytes. The length is the number of rows 
multiplied by number of columns multiplied by size of cell. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


An application using VioGetBuf can prepare a screen in the application’s 
own logical video buffer (LVB) offline. When the application is in the fore- 
ground, the physical screen buffer is updated from LVB when Vi oShowBuf is 
issued. When the application runs in the background, the physical screen 
buffer is updated when the application is switched to the foreground. 


Once VioGetBuf is issued, all VioWrtXX calls issued while the application 
is running in the foreground are written to the physical display buffer and 
LVB. If a VioGetPhysBuf is subsequently issued, then the VioWrtXX calls 
are only written to the physical display buffer. They are no longer written 
to the LVB. 


VioGetMode may be used to determine the dimensions of the buffer. 
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If VioSetMode is issued following a VioGetBuf call, the size of the logical 
video buffer is adjusted to correspond to the new mode. There is one logi- 
cal video buffer per session (or presentation space if AVIO application) that 
corresponds to the current mode on the current display configuration. 


PM considerations 


This function returns the address and length of the Advanced VIO presen- 
tation space. The presentation space may be used to directly manipulate 
displayed information. 
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VioGetConfig (FAPI) 


Description 


This call returns the video display configuration. 


+#define INCL_VIO 
include <oOs2 hp 


USHORT VioGetConfig (USHORT usConfigId, PVIOCONFIGINFO pvioin, 
HVIO hvio); 


usConfigId (USHORT) - input 
Identifies for which display configuration information is being requested: 


Value Definition 


O Current configuration 
(usConfiglId == VIO_CONFIG_CURRENT) 
1 Primary configuration 
(usConfiglId == VIO_CONFIG_PRIMARY) 
2 Secondary configuration. 
(usConfiglId == VIO_CONFIG_SECONDARY) 


pvioin (PVIOCONFIGINFO) - output 
Address of structure where the display configuration is returned. 


cb (USHORT ) 

The maximum size structure required is variable and can be deter- 
mined by issuing VioGetConfig with Length set to 2. When cb is set 
to 2 on input, VioGetConfig returns the size of the maximum struc- 
ture required in the cb field on output. When cb is not equal to 2 
on input, the cb field is modified on output to reflect the actual 
number of bytes returned. That is, if more than the maximum size 
was specified, the maximum size is returned. However, if less than 
the maximum size is specified, the value returned reflects the 
number of bytes of complete fields returned. 


adapter (USHORT ) 
Display adapter type. 


Value Definition 


QO |§Monochrome-compatible 
(adapter == DISPLAY_MONOCHROME) 
1 Color Graphics Adapter (CGA) 
(adapter == DISPLAY_CGA) 
2 Enhanced Graphics Adapter (EGA) 
(adapter == DISPLAY_EGA) 
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Value Definition 


3 


4—6 


VGA or PS/2 Display Adapter 

(adapter == DISPLAY_VGA) 

Reserved 

IBM Personal System/2 Display Adapter 8514/A. 
(adapter == DISPLAY_8514A) 

IBM PS/2 Image Adapter/A 

(adapter == DISPLAY_IMAGEADAPTER) 

IBM PS/2 XGA Display Adapter 

(adapter == DISPLAY_XGA) 


Values ranging from O-4095 are reserved for IBM. 


display (CUSHORT ) 
Display or monitor type. 


Value Definition 


O 


1 


2 


3 


4 


5-8 
9 


10 


11 


12 


13 


Monochrome display 

(display == MONITOR_MONOCHROME) 
Color display 

(display == MONITOR_COLOR) 
Enhanced Color Display 

(display == MONITOR_ENHANCED) 
PS/2 Monochrome Display 8503 
(display == MONITOR_8503) 

PS/2 Color Displays 8512 and 8513 
(display == MONITOR_851X_COLOR) 
Reserved 

PS/2 Color Display 8514 

(display == MONITOR_8514) 

IBM Plasma Display Panel 

(display == MONITOR_FLATPANEL) 
Monochrome Displays 8507 and 8604 
(display == MONITOR_8507_8604) 
PS/2 Color Display 8515 

(display == MONITOR_8515) 

Reserved 


Values ranging from O-4095 are reserved for IBM. 


cbMemory (ULONG) 
Amount of memory, in bytes, on the adapter. 


Configuration (USHORT ) 
Number of the display configuration that this data corresponds to. 
This is assigned by the video subsystem, not the Base Video Handler 


(BVH). 


VDHVersion (USHORT ) 
This field is reserved. 
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Flags (USHORT) 
Bit field defined as follows: 


Bit Description 


15-1 Reserved 
O Power up display configuration. 


HWBufferSize (ULONG) 
Size of the buffer required by the Base Video Handler (BVH) to save 
the full hardware state excluding the physical display buffer. 


FullSaveSize (ULONG) 
Maximum size buffer required by the BVH to save the full physical 
display buffer. 


PartSaveSize (ULONG) 
Maximum size buffer required by the BVH to save the portion of the 
physical display buffer that is overlaid by a pop-up. 


EMAdaptersOFF (USHORT ) 
Offset within the configuration data structure to the following in- 
formation describing what other display adapters are emulated by 
this display adapter. 


Number of Data words (USHORT) 
Contains a one-word field specifying a count of data words to follow. 


Data word 1 (USHORT) 
Bits set in the data words identify display adapters emulated. Data 
word 1 has the following definition: 


Bit Description 
QO Monochrome/printer adapter 
(data[O] & (1 << DISPLAY_MONOCHROME)) 
1 Color graphics adapter 
(data[O] & (1 << DISPLAY_CGA)) 
2 Enhanced graphics adapter 
(data[O] & (1 << DISPLAY_EGA)) 
3 VGA or PS/2 display adapter 
(data[O] & (1 << DISPLAY_VGA)) 
4-6 Reserved 
7 8514/A Adapter 
(data[O] & (1 << DISPLAY_8514A)) 
8 IBM PS/2 Image Adapter/A 
(data[O] & (1 << DISPLAY_IMAGEADAPTER)) 
9 IBM PS/2 XGA Adapter 
(data[O] & (1 << DISPLAY_XGA)) 
10-15 Reserved. 
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Data word 2 (USHORT) 
Reserved. 


Data word N (USHORT) 
Reserved. 


EMDisplaysOFF (USHORT ) 
Offset within the configuration data structure to the following infor- 
mation describing what other displays are emulated by this display. 


Number of Data words (USHORT) 
One-word field specifying a count of data words to follow. 


Data word 1 (USHORT) 
Bits set in the data words identify displays emulated. Data word 1 
has the following definition: 


Bit Description 
5151 monochrome display 
5153 color display 
5154 enhanced color display 
8503 monochrome display 
8512 or 8513 color display 
8 Reserved 
9 8514 color display 
10 IBM Plasma Display Panel 
11 Monochrome Displays 8507 and 8604 
12 8515 color display 
13-15 Reserved. 


TRwnro 


Data word 2 (USHORT) 
Reserved 


Data word N (USHORT) 
Reserved. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager appli- 
cation, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
421 ERROR_VIO_INVALID_PARMS 
436 ERROR_VIO_INVALID_HANDLE 
438 ERROR_VIO_INVALID_LENGTH 
465 ERROR_VIO_DETACHED 
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Remarks 

The values returned may not be correct if the adapter cannot be properly 
identified by the Base Video Handler (BVH) selected at system installation 
time. It can also be incorrect if the physical setup does not match that in- 
dicated by the presence of the adapter or by adapter switches. For exam- 
ple, it is impossible to detect the absence of a display on a CGA or the 
display attached to an EGA, despite the setup switches. 
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VioGetCp (xPM) 


Description 


This call allows a process to query the code page currently used to display 
text data. 


ttKdefine INCL_VIO 
include <os2.h> 


USHORT VioGetCp (USHORT usReserved, PUSHORT pIdCodePage, HVIO hvio); 


usReserved (USHORT) - input 
A reserved word of Os. 


pIdCodePage (PUSHORT) - output 
Address of a word in the application’s data area. The current video 
code page is returned in this word. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
468 ERROR_VIO_USER_FONT 


Remarks 


The display code page ID previously set by VioSetCp, or inherited from the 
requesting process, is returned to the caller. 


The code page tag returned is the currently active code page. A value of 
0000 indicates that the code page in use is the ROM code page provided by 
the hardware. 


If ERROR_VIO_USER_FONT is returned, it indicates a user font that was 
previously loaded with VioSetFont is the active code page. 
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VioGetCurPos (FAPI) 


Description 


This call returns the coordinates of the cursor. 


define INCL_VIO 
#Finclude <os2.h> 


USHORT VioGetCurPos (PUSHORT pusRow, PUSHORT pusColumn, HVIO hvio); 


pusRow (PUSHORT) - output 
Address of the current Row position of the cursor where 0 is the top row. 


pusColumn (PUSHORT) - output 
Address of the current column position of the cursor where O is the 
leftmost column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
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VioGetCurlype (FAPI) 


Description 
This call returns the cursor type. 


#tdefine INCL_VIO \ 
#include <os2.h> 


USHORT VioGetCurType (PVIOCURSORINFO pvioCursorInfo, HVIO hvio); 


pvioCursorInfo (PVIOCURSORINFO) - output 
Address of the cursor characteristics structure: 


yStart (USHORT ) 
Horizontal scan line in the character cell that marks the top line of 
the cursor. If the character cell has n scan lines, O is the top scan 
line of the character cell and (n-1) is the bottom scan line. 


cEnd (USHORT) 
Horizontal scan line in the character cell that marks the bottom 
line of the cursor. Scan lines within a character cell are numbered 
as defined in yStart. 


cx (CUSHORT ) 
Width of the cursor. In text modes, cursorwidth is the number of 
columns. The maximum number supported by the OS/2 base video 
subsystem is 1. In graphics modes, cursorwidth is the number of pels. 


attr (USHORT) 
A value of —1 denotes a hidden cursor, all other values in text mode 
denote normal cursor and in graphics mode denote color attribute. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager ap- 
plication, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 
If CursorStartLine and CursorEndLine were originally specified as percent- 


ages on VioSetCurType (using negative values), the positive values into 
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which they were translated are returned. Refer to VioSetCurType for more 
information on how percentages can be used to set CursorStartLine and 
CursorEndLine independent of the number of scan lines per character cell. 


Family API considerations 


In DOS mode, VioGetCurType returns only two values for attr: O = visible 
cursor, and —1 = hidden cursor. 


Video (VIO) functions 91 


VioGetFont (FAPI, xWPM) 


Description 


This call returns either the font table of the size specified or the font in use. 


4tdefine INCL_VIO 
Finiclude <os2.h> 


USHORT VioGetFont (PVIOFONTINFO pviofi, HVIO hvio); 


pviofi (PVIOFONTINFO) - input/output 
Address of the font structure that returns current RAM font or speci- 
fied ROM or code page font depending on the request type: 


cb (USHORT) 
Length of structure, including cb. 


14 Only valid value. 


type (USHORT) 
Request type: 


Value Definition 
QO Get current RAM font for EGA, VGA, or IBM Personal Sys- 
tem/2 Display Adapter. 
(type == VGFI_LGETCURFONT) 
1 Get ROM font for CGA, EGA, VGA, or IBM Personal System/2 
Display Adapter. 
(type == VGFI_LGETROMFONT) 


cxCell (USHORT ) , 
Pel columns in character cell. 


cyCell (CUSHORT) 
Pel rows in character cell. 


pbData (PVOID) 
Address of the requested font table returned in a caller-supplied data 
area. If the storage area is accessed by way of an address of O, a sys- 
tem-supplied segment containing the requested font table is returned. 


cbData (USHORT ) 


Length, in bytes, of the caller-supplied data area where the font 
table is returned. 


hvio (HVIO) - input 
Reserved word of Os. 


92 Video (VIO) functions 


Return value 


QO NO_ERROR 
355 ERROR_VIO_MODE 
421 ERROR_VIO_INVALID_PARMS 
438 ERROR_VIO_INVALID_LENGTH 
465 ERROR_VIO_DETACHED 
467 ERROR_VIO_FONT 
494 ERROR_VIO_EXTENDED_SG 


Remarks 


For reqtype = 1, return ROM font, the font size requested must be sup- 
ported by the display adapter installed. The 8x8, 8x14, 9x14, 8x16, or 9x16 
character font may be requested for the VGA or PS/2 Display Adapters. The 
8x8, 8x14, or 9X14 font may be requested for the enhanced graphics 
adapter. The 8x8 font may be requested for the color graphics adapter. 


Note Although graphics mode support is provided in VioGetFont, this 
support is not provided by the Base Video Handlers provided with OS/2. 


For reqtype = 1, return ROM font, the far address returned is a ROM pointer 
only for those fonts where the font table for the full 256-character set is ac- 
tually contained in ROM. Otherwise, the far address returned is a RAM 
pointer. Note that for 8x8 on the CGA, the font table for the full 256-charac- 
ter set is returned. For 9X14 or 9x16 the font table for the full 256-character 
set is also returned. Partial fonts are not returned. The 9x14 and 9x16 fonts 
are derived from variations of the 8x14 and 8x16 fonts, respectively, where 
the definitions of fonts for those characters that are different are replaced. 


For VioGetFont specifying reqtype = 1, return ROM font, the font returned 
is derived from the fonts contained in the system, EGA, VGA, and PS/2 
Display Adapter BIOS data areas as applicable. There is an exception for 
the EGA, VGA and PS/2 Display Adapter when VioSetCp or VioSetFont 
has been issued. In that case, the font of the size requested is returned 
from the active code page or the list of user fonts already set. 
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VioGetMode (FAPI, xPM) 


Description 
This call returns the mode of the display. 


4tKdefine INCL_VIO 
4#FAinclude <os2.h> 


USHORT VioGetMode (PVIOMODEINFO pvioModelInfo, HVIO hvio); 


pvioModeInfo (PVIOMODEINFO) - input/output 
Far address of a structure where mode characteristics are returned. 


cb (USHORT) 

Input parameter to VioGetMode. Length specifies the length of the 
data structure in bytes including Length itself. The value specified on 
input controls the amount of mode data returned. The minimum 
structure size required is 2 bytes, and the maximum structure size 
required is 34 bytes. A length of 2 returns the size of the maximum 
structure required for all the mode data. When length is not equal to 
2, the length field is modified on output to reflect the actual number 
of bytes returned. 


fbType CUCHAR) 
Mode characteristics bit mask: 


Bit Description 


7-4 Reserved 
3 O = VGA-compatible modes O thru 13H 
1 = Native mode 
2 O = Enable color burst 
'(fbType & VGMT_DISABLEBURST) 
1 = Disable color burst 
(fbType & VGMT_DISABLEBURST) 
1 O = Text mode 
!(fbType & VGMT_GRAPHICS) 
1 = Graphics mode 
(fbType & VGMT_GRAPHICS) 


O O = Monochrome compatible mode 
'(fbType & VGMT_OTHER) 
1 = Other. 


(fbType & VGMT_OTHER) 


color (UCHAR) 
Number of colors defined as a power of 2. This is equivalent to the 
number of color bits that define the color, for example: 
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Value Definition 
O Monochrome modes 7, 7+, and F. 
1 2 colors 
2 4 colors 
4 16 colors 
8 256 colors 


col (USHORT) 
Number of text columns. 


row (USHORT) 
Number of text rows. 


hres (USHORT) 
Horizontal resolution, number of pel columns. 


vres (USHORT ) 
Vertical resolution, number of pel rows. 


fmt_ID (UCHAR) 
Format of the attributes. 


attrib (UCHAR) 
Number of attributes in a character cell. 


buf_addr (ULONG) 
32-bit physical address of the physical display buffer for this mode. 


buf_length (ULONG) 
Length of the physical display buffer for this mode. 


full_length (ULONG) 
Size of the buffer required for a full save of the physical display 
buffer for this mode. 


partial_length (ULONG) 
Size of the buffer required for a partial (pop-up) save of the physi- 
cal display buffer for this mode. 


ext_data_addr (PCH) 
Far address to an extended mode data structure or zero if none. 
The format of the extended mode data structure is determined by 
the device driver and is unknown to OS/2. 


hvio (HVIOQ) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
436 ERROR_VIO_INVALID_HANDLE 
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438 ERROR_VIO_INVALID_LENGTH 
465 ERROR_VIO_DETACHED 
494 ERROR_VIO_EXTENDED_SG 


Remarks 


Refer to VioSetMode for examples. 
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VioGetPhysBuf (FAPI, xWPM) 


Description 
This call gets addressability to the physical display buffer. 


4tdefine INCL_VIO 
ei nclude <os2.h> 


USHORT VioGetPhysBuf (PVIOPHYSBUF pvioPhysBuf, USHORT usReserved) ; 


pvioPhysBuf (PVIOPHYSBUF) - input/output 
Address of the data structure that contains the physical display buffer 
address and length on input and returns the selectors used to address 
the display buffer. 


pBuf (PBYTE) 
Address of the 32-bit start address (selector:offset) of the physical 
display buffer passed as input. If displaybuflen is O, then display- 
bufaddr is the far address of the PhysBuf block described below. 


cb (ULONG) 
32-bit length of the physical display buffer. If displaybuflen is O, 
then displaybufaddr is treated as the far address of the PhysBuf 
block described later and the Selector List is not present. 


asel (SEL) 
Selector list. 


Returns the selectors (each of word-length) that address the phys- 
ical display buffer. The first selector returned in the list, addresses 
the first 64K of the physical display buffer or displaybuflen, 
whichever is smaller. If displaybuflen is greater than 64K, the sec- 
ond selector addresses the second 64K. 


The last selector returned in the list addresses the remainder of the 
display buffer. The application is responsible for ensuring enough 
space is reserved for the selector list to accommodate the specified 
buffer length. 


Layout of the PhysBuf block pointed to by pBuf. The PhysBuf block is 
a variable length data structure. The first word is the Length of the 
PhysBuf block in bytes. The remaining words of the structure are the 
selectors that address the physical video buffer. If Length is specified 
as 2, the required length of the Phys8uf Block is returned in its place. 


length (USHORT ) 
Length of PhysBuf structure in bytes 
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selector (SEL) 
First selector 


selector (SEL) 
Next selector 


selector (SEL) 


selector (SEL) 
Last selector 


Reserved (USHORT) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
350 ERROR_VIO_PTR 
429 ERROR_VIO_IN_BG 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
494. EKRROR_VIO_EXTENDED_SG 


Remarks 


If displaybuflen = O, VioGetPhysBuf returns a selector that addresses the 
physical display buffer corresponding to the current mode. One selector is 
returned in Selector List. If a VioGetPhysBuf is issued after a VioGetBuf, 
then all VioWrtXX calls will no longer be written to the LVB. They will only 
be written to the physical display buffer. An application uses VioGetPhys 
Buf to get addressability to the physical display buffer. The selector re- 
turned by VioGetPhysBuf may be used only when an application program 
is executing in the foreground. When an application wants to access the 
physical display buffer, the application must call VioScrLock. VioScrLock 
either waits until the program is running in the foreground or returns a 
warning when the program is running in the background. For more infor- 
mation refer to VioScrLock and VioScrUnLock. 


The buffer range specified for the physical screen buffer must fall between 
hex ‘AOOOO’ and ‘BFFFF’ inclusive. An application may issue Vi oGetPhysBuf 
only when it is running in the foreground. An application may issue Vio 
GetPhysBuf more than once. 
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VioGetState (FAPI, xWPM) 


Description 


This call returns the current settings of the palette registers, overscan 
(border) color, blink/background intensity switch, color registers, under- 
line location, or target VioSetMode display configuration. 


define INCL_VIO 
4#Finclude <os2.h> 


USHORT VioGetState (PVOID pState, HVIO hvio); 


pState (PVOID) - input/output 
Address of one of six different state structures, depending on the re- 
quest type. The request type is the second word of the packet. 


Type Definition 

Get palette registers 

Get overscan (border) color 

Get blink/background intensity switch 

Get color registers 

Reserved 

Get the scan line for underlining 

Get target VioSetMode display configuration. 
Reserved. 


NOP WNFe © 


The six structures, depending on request type, are: 


VIOPALSTATE 
Applies to EGA, VGA, or IBM Personal System/2 Display Adapter. 


cb (USHORT) - input 
Length of structure, including length. 


38 Maximum valid value. 


type (USHORT) - input 
Request type O for palette registers. 


iFirst CUSHORT) - input 
First palette register in the palette register sequence; must be spec- 
ified in the range O through 15. The palette registers are returned 
in sequential order. The number returned is based upon cb. 


acolor (USHORTLE(cb-6)/2]) - output 
Color value for each palette register. The maximum number of en- 
tries in the color value array is 16. 
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VIOOVERSCAN 
Applies to CGA, VGA, or IBM Personal System/2 Display Adapter. 


cb (USHORT) - input 
Length of structure, including cb. 


6 Only valid value. 


type (USHORT) - input 
Request type 1 for overscan (border) color. 


color (USHORT)- input 
Color value. 


VIOINTENSITY 
Applies to CGA, EGA, MCGA, VGA, or IBM Personal System/2 Display 
Adapter. 


cb (USHORT) - input 
Length of structure, including cb. 


6 Only valid value. 


type (USHORT) - input 
Request type 2 for blink/background intensity switch. 


fs (USHORT) - output 
Switch set as: 
Value Definition 


O Blinking foreground colors enabled. 
i High intensity background colors enabled. 


VIOCOLORREG 
Applies to VGA, or IBM Personal System/2 Display Adapter. 


cb (USHORT) - input 
Length of structure, including cb. 


12 Length in bytes. 


type (USHORT) - input 
Request type 3 for color registers. 


firstcolorreg (USHORT) - input 
First color register to get in the color register sequence; must be 
specified in the range O through 255. The color registers are re- 
turned in sequential order. 


numcolorregs (USHORT) - input 
Number of color registers to get; must be specified in the range 1 
through 256. 


colorregaddr (PCH) - input 
Far address of a data area where the color registers are returned. 
The size of the data area must be three bytes times the number of 
color registers to get. The format of each entry returned is as follows: 
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Byte 1 Red value 
Byte 2 Green value 
Byte 3 Blue value 
VIOSETULINELOC 
Applies to EGA, VGA, or IBM Personal System/2 Display Adapter. 
cb (USHORT) - input 
Length of structure, including cb. 
6 Length in bytes. 
type (USHORT) - input 
Request type 5 to get the scan line for underlining. Underlining is 
enabled only when the foreground color is 1 or 9. 
scanline (USHORT) - output 
The value returned is in the range O through 31 and is the scan line 
minus 1. A value of 32 means underlining is disabled. 
VIOSETTARGET 
cb (USHORT) - input 
Length of structure, including cb. 
6 Length in bytes. 
type (USHORT) - input 
Request type 6 to get display configuration selected to be the target 
of the next VioSetMode. 


defaultalgorithm (USHORT) - output 
Configuration: 
Value Definition 
O Default selection algorithm. See VioSetMode. 
] Primary 
2 Secondary. 
hvio (HVIQO) - input 
Reserved word of Os. 


Return value 


O 
355 
421 
436 
438 
465 
494 


NO_ERROR 
ERROR_VIO_MODE 
ERROR_VIO_INVALID_PARMS 
ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_INVALID_LENGTH 
ERROR_VIO_DETACHED 
ERROR_VIO_EXTENDED_SG 


Family API considerations 


Request type = 6, Get Target VioSetMode Display Configuration, and re- 
quest type = 5, Get Underline Location, are not supported in the Family API. 
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VioGlobalReg (xWPM) 


Description 


VioGlobalReg allows a subsystem to receive notification at the completion 
of VIO calls issued by all applications running in full-screen sessions. 


define INCL_VIO 
4#Finclude <os2.h> 


USHORT VioGlobalReg(PSZ pszModName, PSZ pszEntryName, ULONG flFunl, 
ULONG flFun2,USHORT usReturn); 


pszModName (PSZ) - input 
Address of the ASCIIZ string containing the 1-8 character filename 
of the subsystem. The maximum length of the ASCIIZ string is 9 
bytes including the terminating byte of zero. The module must be a 


dynamic link library but the name supplied must not include the 
.DLL extension. 


pszEntryName (PSZ) - input 
Address of the ASCIIZ name string containing the dynamic link en- 
try point name of the routine in the subsystem to receive control 
when any of the registered functions is called. The maximum length 


of the ASCHZ string is 33 bytes including the terminating byte of 
Zero. 


flFunl (ULONG) - input 
A bit mask where each bit identifies a video function being registered. 
The bit definitions are shown below. The first word pushed onto the 
stack contains the high-order 16 bits of the function mask, and the 
second word contains the low-order 16 bits. 


Bit Registered function Mask 


31 VioPrtScToggle (flFunl & VR_VIOPRTSCTOGGLE) 
30 VioEndPopUp (lFunl & VR_VIOENDPOPUP) 

29 VioPopUp (flFunl & VR_VIOPOPUP) 

28 VioSavRedrawUndo (lFunl & VR_VIOSAVREDRAWUNDO) 
27 VioSavRedrawWait (lFunl & VR_VIOSAVREDRAWWAIT) 
26 VioScrUnLock (lFunl & VR_VIOSCRUNLOCK) 

25 VioScrlock (lFunl & VR_VIOSCRLOCK) 

24 VioPrtSc (flFunl & VR_VIOPRTSC) 

23 VioGetAnsi (lFunl & VR_VIOGETANS]) 

22 VioSetAnsi (flFunl & VR_VIOSETANSD 

ZL V¥ieScro| Rt (flFunl & VR_VIOSCROLLRT) 

20 VioScrollLlf (flFunl & VR_VIOSCROLLLF) 

19 VioScrol1Dn (flFunl & VR_VIOSCROLLDN) 
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bd 
00 


VioScrollUp (flFunl & VR_VIOSCROLLUP) 
VioWrtCellStr (lFunl & VR_VIOWRTCELLSTR) 


— 
N] 


16 VioWrtCharStrAtt (flFunl & VR_VIOWRTCHARSTRATT) 
15 VioWrtCharStr (f1Funl & VR_VIOWRTCHARSTR) 
14 VioWrtTTY (flFunl & VR_VIOWRTTTY) 

13° VioWrtNCell (f1Funl & VR_VIOWRTNCELL) 

12 VioWrtNAttr (f1Funl & VR_VIOWRTNATTR) 

11 VioWrtNChar (flFunl & VR_VIOWRTNCHAR) 

10 VioReadCellStr (flFunl & VR_VIOREADCELLSTR) 
9 VioReadCharStr (flFunl & VR_VIOREADCHARSTR) 
8 VioShowBuf (flFunl & VR_VIOSHOWBUF) 

7 VioSetMode (flFunl & VR_VIOSETMODE) 

6 VioSetCurType (flFunl & VR_VIOSETCURTYPE) 
5 VioSetCurPos (fl1Funl & VR_VIOSETCURPOS) 
4 VioGetPhysBuf (flFunl & VR_VIOGETPHYSBUF) 
3 VioGetBuf (f1Funl & VR_VIOGETBUF) 

2 VioGetMode (f1Funl & VR_VIOGETMODE) 

1 VioGetCurType (flFunl & VR_VIOGETCURTYPE) 
O VioGetCurPos (flFunl & VR_VIOGETCURPOS) 


flFun2 (ULONG) - input 
A bit mask where each bit identifies a video function being registered. 
The bit mask has the format shown below. The first word pushed onto 
the stack contains the high-order 16 bits of the function mask, and the 
second word contains the low-order 16 bits. Unused bits are reserved 
and must be set to zero. 


Bit Registered function Mask 


31-11 Reserved, must be set to zero. 

10 VioDeRegister (flFun2 & VR_VIODEREGISTER) 
VioRegister (flFun2 & VR_VIOREGISTER) 
VioSetState (flFun2 & VR_VIOSETSTATE) 
VioGetState (l1Fun2 & VR_VIOGETSTATE) 
VioSetFont (flFun2 & VR_VIOSETFONT) 
VioGetCp (flFun2 & VR_VIOGETCP) 
VioSetCp (f1[Fun2 & VR_VIOSETCP) 
VioGetConfig (f1Fun2 & VR_VIOGETCONFIG) 
VioGetFont (flFun2 & VR_VIOGETFONT) 

Vi oModeUndo (f1Fun2 & VR_VIOMODEUNDO) 
VioModeWait (flFun2 & VR_VIOMODEWAIT) 


OrFNWHAH ODN © O 


usReturn (LONG) - input 
Reserved and must be zero. 


Return value 


O NO_ERROR 
349 ERROR_VIO_INVALID_MASK 
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403 ERROR_VIO_INVALID_ASCIIZ 
426 ERROR_VIO_REGISTER 
494 ERROR_VIO_EXTENDED_SG 


Remarks 


Notification of VIO calls issued within the hard error handler and DOS 
(real mode) sessions is not provided. 


When control is routed to EntryPoint, the stack appears as it did after 
the original VIO call except that four additional values have been pushed 
onto the stack. The first is the index number (WORD) of the routine 
called. The second is a near pointer (WORD). The third is the caller’s DS 
register (WORD). The fourth is the return address (DWORD) to the VIO 
router. 


For example, if VioSetCurPos were a registered function, the stack would 
appear as if the following instruction sequence were executed if 
VioSetCurPos were called and control routed to EntryPoint: 


PUSH WORD Row 

PUSH WORD Column 

PUSH WORD hvio 

CALL FAR VioSetCurPos 

PUSH WORD Index 

CALL NEAR Entry point in Vio router 
PUSH WORD Caller’s DS 

CALL FAR Dynamic link entry point 


The index numbers that correspond to the registered functions are listed 
below: 


O VioGetPhysBuf 16 VioWrtCellStr 

1 VioGetBuf 17 VioWrtITy 

2 VioShowBuf 18 VioScrollUp 

3 VioGetCurPos 19 VioSero] 1 Dn 

4 VioGetCurType 20 VioScrollLf 

5 VioGetMode 21 VioScrolIRt 

6 VioSetCurPos 22 VioSetAnsi 

7 VioSetCurType 23 VioGetAnsi 

8 VioSetMode 24 VioPrtSc 

9 VioReadCharStr 25 VioScrLock 
10 VioReadCel1lStr 26 VioScrUnLock 
11 VioWrtNChar 27 VioSavRedrawWait 
12 VioWrtNAttr 28 VioSavRedrawUndo 
13 VioWrtNCel | 29 VioPopUp 
14 VioWrtCharStr 30 VioEndPopUp 


15 VioWrtCharStrAtt 31 VioPrtScToggle 


104 Video (VIO) functions 


32 VioModeWait 38 VioSetFont 


33 VioModeUndo 39 VioGetState 
34 VioGetFont 40 VioSetState 
35 VioGetConfig Al VioRegister 
36 VioSetCp 42 VioDeRegister 


37 VioGetCp 


On entry to the global subsystem, AX contains the return code that is 
returned to the application that issued the VIO call. The global subsystem 
must return with all stack parameters and all general purpose registers, 
including AX, restored to the same values as on entry. 


All VIO functions within a session are serialized on a thread basis. That is, 
when a global subsystem receives control, it can safely assume that it is not 
called again from the same session until the current call has completed. 
Note, however, that VIO calls across different sessions are not serialized. 


VioGlobalReg may only be issued during system initialization. After sys- 
tem initialization, VioGlobalReg returns ERROR_VIO_REGISTER. A glob- 
ally registered subsystem is active for the life of the system. 


If multiple global subsystems are registered, they are given control in the 
order that they are registered. 


A globally registered subsystem receives control on VIO calls issued from 
all full-screen sessions except the hard error handler and DOS (real mode) 
sessions. 
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VioModeUndo (xWPM) 


Description 


This call allows one thread within a process to cancel a Vi oModeWait issued 
by another thread within the same process. 


ftdefine INCL_VIO 
fHinclude <os2.h> 


USHORT VioModeUndo (USHORT usOwnerInd, USHORT uskillind, 
USHORT usReserved); 


usQwnerInd (USHORT) - input 
Indicates whether the thread issuing VioModeUndo wants ownership 
of VioModeWait to be reserved for its process. 


Value Definition 


O Reserve ownership 
(usOwnerInd == UNDOI_GETOWNER) 
1 Give up ownership 
(usOwnerInd == UNDOI_LRELEASEOWNER) 


usKillInd (USHORT) - input 
Indicates whether the thread (with the outstanding VioModeWait) 
should be returned an error code or be terminated. 


Value Definition 


O Return error code 

(usKillInd == UNDOK_ERRORCODE) 
: Terminate thread. 

(usKillInd == UNDOK_TERMINATE) 


usReserved (USHORT) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
421 ERROR_VIO_INVALID_PARMS 
422 ERROR_VIO_FUNCTION_OWNED 
427 ERROR_VIO_NO_MODE_THREAD 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
465 ERROR_VIO_DETACHED 
486 ERROR_VIO_BAD_RESERVE 
494 ERROR_VIO_EXTENDED_SG 
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Remarks 

VioModeUndo may be issued only by a thread within the process that owns 
VioModeWait. The thread issuing VioModeUndo can either reserve owner- 
ship of the VioModeWait function for its process or give up ownership. The 
thread whose \VioModeWait is cancelled is optionally terminated. 
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VioModeWait (xWPM) 


Description 


This call allows a graphics mode application to be notified when it must re- 
store its video mode, state, and modified display adapter registers. The re- 
turn from this function call provides the notification. 


ttdefine INCL_VIO 
#Finclude <os2.h> 


USHORT VioModeWait (USHORT usReqlype, USHORT pNotifyType, 
USHORT usReserved) ; 


usReql ype (USHORT) - input 
Application request event. RequestType = O indicates that the applica- 
tion wants to be notified at the end of a pop-up to restore its mode. 
RequestType = O is the only event supported by Vi oModeWait. 


pNotifylype (PUSHORT) - output 
Address of the operation to be performed by the application returning 
from VioModeWait. NotifyType = O, indicating restore mode, is the only 
type of notification returned. 


usReserved (USHORT) - input 
Reserved word of Os. 


Return value 


QO NO_ERROR 
421 ERROR_VIO_INVALID_PARMS 
422 ERROR_VIO_FUNCTION_OWNED 
423 ERROR_VIO_RETURN 
424 ERROR_SCS_INVALID_FUNCTION 
428 ERROR_VIO_NO_SAVE_RESTORE_THD 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
465 ERROR_VIO_DETACHED 
494 ERROR_VIO_EXTENDED_SG 


Remarks 


At the completion of an application or hard error pop-up (reference 
VioPopUp), OS/2 notifies the session that was originally interrupted for the 
pop-up to restore its mode. The return from this function call provides that 
notification. The thread that issued the call must perform the restore and 
then immediately reissue Vi oModeWait. 
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When an application’s VioModeWait thread is notified, the thread must re- 
store its video mode, state, and modified display adapter registers. An ap- 
plication’s Vi oModeWait thread does not restore the physical display buffer. 
OS/2 saves/restores the physical display buffer over a pop-up. 


Only one process for a session can issue VioModeWait. The first process 
that issues VioModeWait becomes the owner of this function. (Refer to 
Vi oModeUndo.) 


An application must issue VioModeWait only if it writes directly to the reg- 
isters on the display adapter. Otherwise, the application can allow OS/2 to 
perform the required restore by not issuing Vi oModeWait. 


When an application issues VioModeWait, it is also required to issue 
Vi oSavRedrawWait to be notified at screen switch time to perform a full save 
or restore (reference VioSavRedrawWait.) Two application threads must be 
dedicated to performing these operations. 
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VioPopUp (xPM) 


Description 


This call is issued by an application process when it requires a temporary 
screen to display a momentary message to the user. 


#tdefine INCL_VIO 
4Hinclude <os2.h> 


USHORT VioPopUp (PUSHORT pflags, HVIO hvio); 


pflags (PUSHORT) - input 
Address of the bit flags that indicates which options to the application 
are being selected. 


Bit 


Description 


15-2 Reserved, set to zero. 


1 


O = Non-transparent operation. The video mode is set to text- 
mode 3, 3*, 3+, 7, or 7+. The highest resolution supported by 
the primary display adapter configured in the system is se- 
lected. The screen is cleared, and the cursor is positioned in the 
upper left corner of the display. 

'(*pflags & VP_TRANSPARENT) 

1 = Transparent operation. If the video mode of the outgoing 
foreground session is text (mode 2, 3, 7, or one of the * or + 
variations of these modes), no mode change occurs. The 
screen is not cleared, and the cursor remains in its current 
position. If transparent operation is selected, and if the video 
mode of the outgoing foreground session is not text (or if the 
outgoing foreground session has a VioSavRedrawWait thread), 
the pop-up request is refused. A unique error code ER- 
ROR_VIO_TRANSPARENT_POPUP is returned in this case. 
(*pflags & VP_TRANSPARENT) 

OS/2 is responsible for saving and restoring the physical dis- 
play buffer of the previous foreground session around a pop-up. 
This is true whether transparent or non-transparent operation 
is selected. 

O = Return with unique error code ERROR_VIO_EXISTING_POPUP 
if pop-up is not immediately available. 

!(*pflags & VP_WAIT) 

1 = Wait if pop-up is not immediately available. 

(*pflags & VP_WAIT) 


hvio (HVIO) - input 
Reserved words of Os. 
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Return value 


O NO_ERROR 
405 ERROR_VIO_NO_POPUP 
406 ERROR_VIO_EXISTING_POPUP 
483 ERROR_VIO_TRANSPARENT_POPUP 


Remarks 


VioPopUp is normally issued by the application when it is running in the 
background and wishes to immediately display a message to the user 
without waiting to become the active foreground session. 


When an application process issues VioPopUp, it should wait for the return 
from the request. If the process allows any of its threads to write to the 
screen before VioPopUp returns a successful return code, the screen out- 
put may be directed to the application’s normal video buffer rather than to 
the pop-up screen. If the process allows any of its threads to issue key- 
board or mouse calls before \VioPopUp returns a successful return code, the 
input is directed from the application’s normal session. Once the process 
that issued VioPopUp receives a successful return code, video and Key- 
board calls issued by any of the threads in the pop-up process are directed 
to the pop-up screen. This continues until the process issues VioEndPopUp. 
At that time video and keyboard calls resume being directed to the appli- 
cation’s normal video buffer. 


There may be only one pop-up in existence at any time. If a process re- 
quests a pop-up and a pop-up already exists, the process has the choice of 
waiting for the prior pop-up to complete or receiving an immediate return 
with an error code. The error code indicates that the operation failed due 
to an existing pop-up having captured the screen. 


Video pop-ups provide a mechanism for a background application to notify 
the operator of an abnormal event upon which the operator must take 
some action. When considering the suitability of using pop-ups in a par- 
ticular situation, the possible disruptive effect of pop-ups to the operator 
should be considered. If the operator were interrupted frequently by pop- 
ups issued by background applications,the operator would not effectively 
work with the foreground application. 


While a video pop-up is in the foreground, the operator cannot use the hot 
key to switch to another application or to the shell. Before the operator can 
switch another application or the shell to the foreground, the pop-up ap- 
plication must issue VioEndPopUp. 


While a video pop-up is in effect, all video calls from the previous fore- 
ground session are blocked until the process that issued VioPopUp issues 
VioEndPopUp. 
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When VioPopUp is issued, only the process within the session that issued 
VioPopUp is brought to the foreground. Assuming the session was already 
the foreground session, any video calls issued by other processes in that ses- 
sion are blocked until the process that issued VioPopUp issues VioEndPopUp. 


DosExecPgm may not be issued by a process during a pop-up. The following 
video calls are the only calls that may be issued during the pop-up by the 
process that issued VioPopUp: 


VioEndPopUp VieScrolllf 
VioGetConfig VioSetCurPos 


VioGetCp VioSetCurlype 
VioGetFont VioSetCp 
VioGetAnsi VioSetFont 


VioGetState VioSetState 
VioGetCurPos VioWrtNChar 
VioGetCurlype VioWrtNAttr 
VioGetMode VioWrtNCel | 
VioReadCharStr VioWrtCharStr 
VioReadCel!lStr VioWrtCharStrAtt 
VioScrollRt VioWrtCellStr 
VioScrollUp VioWrtTTY 
VioScrollDn 


Selectors to the physical display buffer that the issuing process obtained 
on a prior VioGetPhysBuf call may not be used during the pop-up. 


When an application registers a replacement for Vi oPopUp within a session, 
the registered routine is invoked only when that session is in the fore- 
ground. If VioPopUp is issued when that session is in the background, the 
OS/2 default routine is invoked. If the application’s session is using a key- 
board or mouse monitor, the monitor does not intercept data while the 
pop-up is active. 


PM considerations 


This function can be used from within a PM application. Kbdxxx, Mouxxx, 
and Vioxxx calls (with a zero handle) are all allowed between VioPopUp and 
VioEndPopUp, and are directed to the pop-up screen. An error is returned if 
issued with a non-zero handle. 
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VioPrtSc (xWPM) 


Description 
This call is issued by the Session Manager when the operator presses PrtSc. 


#define INCL_VIO 
#include <os2.h> 


USHORT VioPrtSc (HVIO hvio); 


hvio (HVIO) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
402 ERROR_VIO_SMG_ONLY 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


VioPrtSc supports text modes O through 3, and 7. An Alternate Video Sub- 
system may want to register a replacement for VioPrtSc. An advanced 
video subsystem could set a graphics mode while the mode known to the 
base video subsystem PrtSc routine is text. Then, if the operator presses 
PrtSc, the printer output is unpredictable. VioPrtSc is reserved for use by 
the Session Manager. Application programs may not issue VioPrtSc. 


Three beeps are generated if a hard error is detected while writing to the 
printer. 
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VioPrtScToggle (xWPM) 


Description 


This call is called by the Session Manager when the operator presses Ctrl 
and PrtSc. 


Htdefine INCL_VIO 
include <os2.h> 


USHORT VioPrtScToggle (HVIO hvio); 


hvio (HVIO) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
402 ERROR_VIO_SMG_ONLY 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


VioPrtScToggle toggles the Ctrl and PrtSc state of the foreground session. 
When the Ctrl and PrtSc state is on, all VioWrtTTY calls from that session 
are echoed to the print device. 


VioPrtScToggle can only be called by the Session Manager. If an applica- 
tion issues this call, it receives an error code. 


Three beeps are generated if a hard error is detected while writing to the 
printer. When Ctrl and PrtSc is turned off, the operator may have to press 
the Enter key to cause output spooled while Ctrl and PrtSc was active to 
be printed. This is because the spool files are closed when the next 
VioWrtTTY is executed in the session, such as writing the prompt in re- 
sponse to the Enter Key. 
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VioReadCellStr (FAPI) 


Description 


This call reads a string of character-attribute pairs (cells) from the screen, 
starting at the specified location. 


+#define INCL_VIO 
4include <os2.h> 


USHORT VioReadCel|Str (PCH pchCel!lStr, PUSHORT pcb, USHORT usRow, 
USHORT usColumn, HVIO hvio); 


pchCellStr (PCH) - output 
Address of the buffer where the cell string is returned. 


pcb (PUSHORT) - input/output 
Address of the buffer length in bytes. It must take into account that 
each character-attribute(s) entry in the buffer is 2 or 4 bytes. If the 
length of the buffer is not sufficient, the last entry is not complete. 


usRow (USHORT) - input 
Starting row of the field to read, O is the top row. 


usColumn (USHORT) - input 
Starting column of the field to read, O is the leftmost column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a string read comes to the end of the line and is not complete, the string 
read continues at the beginning of the next line. If the read comes to the 
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end of the screen and is not complete, the read terminates and the length 
is set to the length of the buffer that was filled. 


PM considerations 


VioReadCellStr reads a string of character/attributes (or cells) from the 
Advanced VIO presentation space starting at the specified location. 
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VioReadCharStr (FAPI) 


Description 


This call reads a string of characters from the display starting at the spec- 
ified location. 


+#define INCL_VIO 
#Finclude <os2.h> 


USHORT VioReadCharStr (PCH pchCellStr, PUSHORT pcb, USHORT usRow, 
USHORT usColumn, HVIO hvio); 


pchCellstr (PCH) - output 
Address of the buffer where the character string is returned. 


pcb (PUSHORT) - input/output 
Address of the buffer length in bytes. 


usRow (USHORT) - input 
Starting row of the field to read, O is the top row. 


usColumn (USHORT) - input 
Starting column of the field to read, O is the leftmost column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_ HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a string read comes to the end of the line and is not complete, then the 
string read continues at the beginning of the next line. If the read comes to 
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the end of the screen and is not complete, the read terminates and the 
length is set to the number of characters read. 


PM considerations 


VioReadCharStr reads a character string from the Advanced VIO presenta- 
tion space starting at the specified location. 
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VioRegister (xWPM) 


Description 


This call registers an alternate video subsystem within a session. 


define INCL_VIO 
#include <os2.h> 


USHORT VioRegister (PSZ pszModName, PSZ pszEntryName, 
ULONG flFunl, ULONG flFun2); 


pszModName (PSZ) - input 
Address of the ASCIIZ string containing the 1-8 character filename of 
the subsystem. The maximum length of the ASCIIZ string is 9 bytes 
including the terminating byte of zero. The module must be a dy- 
namic link library but the name supplied must not include the .DLL 
extension. 


pszEntryName (PSZ) - input 
Address of the ASCIIZ name string containing the dynamic link entry 
point name of the routine in the subsystem to receive control when any 
of the registered functions is called. The maximum length of the 
ASCIIZ string is 33 bytes including the terminating byte of zero. 


flFunl CULONG) - input 
A bit mask where each bit identifies a video function being registered. 
The bit definitions are shown below. The first word pushed onto the 
stack contains the high-order 16 bits of the function mask, and the 
second word contains the low-order 16 bits. 


Bit Registered function Mask 


31 VioPrtScToggle (f1Funl & VR_VIOPRTSCTOGGLE) 
30 VioEndPopUp (f1Funl & VR_VIOENDPOPUP) 
29 VioPopUp (f1Funl & VR_VIOPOPUP) 


28 VioSavRedrawUndo (lFunl & VR_VIOSAVREDRAWUNDO) 
27 VioSavRedrawWait (f1Funl & VR_VIOSAVREDRAWWAIT) 


26 VioScrUnLock (f1Funl & VR_VIOSCRUNLOCK) 
25 VioScrLock (flFunl & VR_VIOSCRLOCK) 

24 VioPrtSc (flFunl & VR_VIOPRTSC) 

23 VioGetAnsi (1Funl & VR_VIOGETANSI) 


22 VioSetAnsi (1Funl & VR_VIOSETANS]) 

21 VioScrollRt (f1Funl & VR_VIOSCROLLRT) 
20 VioScrollLf (flFunl & VR_VIOSCROLLLF) 
19 VioScrol1Dn (f1Funl & VR_VIOSCROLLDN) 
18 VioScrollUp (f1Funl & VR_VIOSCROLLUP) 
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Bit Registered function Mask 


pm ee 
mPbOowAb ODN 


be 
OrFNWKHOUAN WO O 


VioWrtCel]Str 
VioWrtCharStrAtt 
VioWrtCharStr 
VioWrtITy 
VioWrtNCel | 
VioWrtNAttr 
VioWrtNChar 
VioReadCel!lStr 
VioReadCharStr 
VioShowBuf 
VioSetMode 
VioSetCurlType 
VioSetCurPos 
VioGetPhysBuf 
VioGetBuf 
VioGetMode 
VioGetCurlType 
VioGetCurPos 


flFun2 (ULONG) - input 
A bit mask where each bit identifies a video function being registered. 
The bit mask has the format shown below. The first word pushed onto 
the stack contains the high-order 16 bits of the function mask, and the 
second word contains the low-order 16 bits. Unused bits are reserved 


and must be set to zero. 


Bit 
Jl=Ll 
10 


OrNWHOAN © O 


(flFunl & VR_VIOWRTCELLSTR) 
(flFunl & VR_VIOWRTCHARSTRATT) 
(flFunl & VR_VIOWRTCHARSTR) 
(f1Funl & VR_VIOWRTTTY) 

(f1Funl & VR_VIOWRTNCELL) 
(1Funl & VR_VIOWRTNATTR) 
(f1Funl & VR_VIOWRTNCHAR) 
(flFunl & VR_VIOREADCELLSTR) 
(flFunl & VR_VIOREADCHARSTR) 
(f1Funl & VR_VIOSHOWBUF) 
(flFunl & VR_VIOSETMODE) 
(flFunl & VR_VIOSETCURTYPE) 
(flFunl & VR_VIOSETCURPOS) 
(flFunl & VR_VIOGETPHYSBUF) 
(f1Funl & VR_VIOGETBUF) 
(flFunl & VR_VIOGETMODE) 
(flFunl & VR_VIOGETCURTYPE) 
(flFunl & VR_VIOGETCURPOS) 


Registered function Mask 
Reserved, must be set to zero. 


VioDeRegister 
VioRegister 
VioSetState 
VioGetState 
VioSetFont 
VioGetCp 
VioSetCp 
VioGetConfig 
VioGetFont 
VioModeUndo 
VioModeWait 


Return value 


O NO_ERROR 
349 ERROR_VIO_INVALID_MASK 
403 ERROR_VIO_INVALID_ASCIIZ 
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(f1Fun2 & VR_VIODEREGISTER) 
(f[Fun2 & VR_VIOREGISTER) 
(f1Fun2 & VR_VIOSETSTATE) 
(flFun2 & VR_VIOGETSTATE) 
(flFun2 & VR_VIOSETFONT) 
(flFun2 & VR_VIOGETCP) 
(flFun2 & VR_VIOSETCP) 
(lFun2 & VR_VIOGETCONFIG) 
(flFun2 & VR_VIOGETFONT) 
(flFun2 & VR_VIOMODEUNDO) 
(flFun2 & VR_VIOMODEWAIT) 


426 ERROR_VIO_REGISTER 

430 ERROR_VIO_ILLEGAL_DURING_POPUP 
465 ERROR_VIO_DETACHED 

494. ERROR_VIO_EXTENDED_SG 


Remarks 


An alternate video subsystem must register which video calls it handles. 
The default OS/2 video subsystem is the Base Video Subsystem. 


When any of the registered functions are called, control is then routed to 
EntryPoint. When this routine is entered, four additional values (5 words) 
are pushed onto the stack. 


The first value is the index number (Word) of the routine being called. 
The second value is a near pointer (Word). The third value is the caller’s 
DS register (Word). The fourth value is the return address (DWord) to 
the VIO router. 


For example, if VioSetCurPos were a registered function, the stack would 
appear as if the following instruction sequence were executed if 
VioSetCurPos were called and control routed to EntryPoint: 


PUSH WORD Row 

PUSH WORD Column 

PUSH WORD hvio 

CALL FAR VioSetCurPos 

PUSH WORD Index 

CALL NEAR Entry point in Vio router 
PUSH WORD Caller’s DS 

CALL FAR Dynamic link entry point 


The index numbers that correspond to the registered functions are 
listed here: 


O VioGetPhysBuf 13 VioWrtNCell 

1 VioGetBuf 14 VioWrtCharStr 
2 VioShowBuf 15 VioWrtCharStrAtt 
3 VioGetCurPos 16 VioWrtCellStr 
4 VioGetCurType 17 VioWrtITY 

5 VioGetMode 18 VioScrollUp 
6 VioSetCurPos 19 VioScrol1Dn 

7 VioSetCurType 20 VioScrollLlf 
8 VioSetMode 21 VioScrollRt 
9 VioReadCharStr 22 VioSetAnsi 
10 VioReadCel|lStr 23 VioGetAnsi 
11 VioWrtNChar 24 VioPrtSc 
12 VioWrtNAttr 25 VioScrLock 
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26 Vioscrunboek 34 VioGetFont 
27 VioSavRedrawWait 35 VioGetConfig 
28 VioSavRedrawUndo 386 VioSetCp 


29 VioPopUp 37 VioGetCp 

30 VioEndPopUp 38 VioSetFont 
31 VioPrtScToggle 39 VioGetState 
32 VioModeWait 40 VioSetState 


33 VioModeUndo 


When a registered function returns to the video router, the return code is 
interpreted as follows: 


Return code = O 
No error. Do not invoke the corresponding Base Video Subsystem 
routine. Return to caller with Return code = O. 


Return code = -1 
No error. Invoke the corresponding Base Video Subsystem routine. 
Return to caller with Return code = return code from Base Video 
Subsystem. 


Return code = error (not O or -1) 
Do not invoke the corresponding Base Video Subsystem routine. 
Return to caller with Return code = error. 


When an application registers a replacement for VioPopUp within a ses- 
sion, the registered routine is only invoked when that session is in the 
foreground. If VioPopUp is issued when that session is in the background, 
the OS/2 default routine is invoked. 


An alternate video subsystem should be designed so the routines regis- 
tered do not cause any hard errors when they are invoked. Otherwise, a 
system lockout occurs. Code and data segments of registered routines, 
that might be loaded from diskette, must be preloaded. 


All VIO functions within a session are serialized on a thread basis. That 
is, when an alternate video subsystem receives control, it can safely as- 
sume that it is not called again from the same session until the current 
call has completed. 
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VioSavRedrawUndo (xWPM) 


Description 


This call allows one thread within a process to cancel a VioSavRedrawWait 
issued by another thread within the same process. 


Htdefine INCL_VIO 
d#Finclude <os2.h> 


USHORT VioSavRedrawUndo (USHORT usOwnerInd, USHORT uskillind, 
USHORT usReserved); 


usOwnerInd (USHORT) - input 
Indicates whether the thread issuing VioSavRedrawUndo wants own- 
ership of VioSavRedrawWait to be reserved for its process. 


Value Definition 


O Reserve ownership 
(usOwnerInd == UNDOIL GETOWNER) 
1 Give up ownership 
(usOwnerInd == UNDOILRELEASEOWNER) 


uSKil]lInd CUSHORT) - input 
Indicates whether the thread with the outstanding VioSavRedrawWait 
should be returned an error code or be terminated. 


Value Definition 


O Return error code 

(usKilllInd == UNDOK_ERRORCODE) 
1 Terminate thread 

(usKillInd == UNDOK_TERMINATE) 


usReserved (HVIO) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
421 ERROR_VIO_INVALID_PARMS 
422 ERROR_VIO_FUNCTION_OWNED 
428 ERROR_VIO_NO_SAVE_RESTORE_THD 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
465 ERROR_VIO_DETACHED 
494. ERROR_VIO_EXTENDED_SG 
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Remarks 

The issuing thread can reserve ownership of VioSavRedrawWait for its pro- 
cess or give it up. The thread whose Vi oSavRedrawWait was cancelled is op- 
tionally terminated. VioSavRedrawUndo may be issued only by a thread 
within the same process that owns VioSavRedrawWait. 
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VioSavRedrawWait (xWPM) 


Description 


This call notifies a graphics mode application when it must save or redraw 
its screen image. 


4tKdefine INCL_VIO 
#Finclude <os2.h> 


USHORT VioSavRedrawWait (USHORT usRedrawInd, PUSHORT pNotifyType, 
SHORT usReserved); 


usRedrawInd (USHORT) - input 
Indicates which events the application is waiting for: 


Value Definition 


O The Session Manager notifies the application for both save and 
redraw operations. 

1 The Session Manager notifies the application for redraw opera- 
tions only. 


pNotifyType (PUSHORT) - output 
Address that specifies the operation to be performed by the application 
upon return from VioSavRedrawWait: 


Value Definition 


O Save screen image 
(*pNotifyType == VSRWN_SAVE) 
1 Restore screen image 
(*pNotifyType == VSRWN_REDRAW) 


usReserved (HVIO) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
421 ERROR_VIO_INVALID_PARMS 
422 ERROR_VIO_FUNCTION_OWNED 
423 ERROR_VIO_RETURN 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
494 ERROR_VIO_EXTENDED_SG 
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Remarks 


OS/2 uses VioSavRedrawWait to notify a graphics mode application to save 
or restore its screen image at screen switch time. The application in the 
outgoing foreground session is notified to perform a save. The application 
in the incoming foreground session is notified to perform a restore. The ap- 
plication must perform the action requested and immediately reissue 
VioSavRedrawWait. When an application performs a save, it saves its phys- 
ical display buffer, video mode, and any other information the application 
needs to completely redraw its screen at restore time. 


Only one process per session can issue VioSavRedrawWait. The process 
that first issues VioSavRedrawWait becomes the owner of the function. 


A text mode application must issue VioSavRedrawWait only if the applica- 
tion writes directly to the registers on the display adapter. Assuming 
VioSavRedrawWait is not issued by a text mode application, OS/2 performs 
the required saves and restores. 


An application that issues VioSavRedrawWait might also need to issue 
VioModeWait. This would allow the application to be notified when it must 
restore its mode at the completion of an application or hard error pop-up. 
Refer to VioModeWait for more information. Two application threads would 
be required to perform these operations in this case. 


At the time a VioSavRedrawWait thread is notified, the session is in transi- 
tion to/from the background. Although the session’s official status is 
background, any selector to the physical display buffer previously ob- 
tained by the VioSavRedrawWait process (through VioGetPhysBuf) is valid 
at this time. The physical display buffer must be accessed without issuing 
VioScrLock. Since the session’s official status is background, any thread 
waits if it issues VioScrLock with the “wait if unsuccessful” option. 


An application containing a VioSavRedrawWait thread should be designed 
so that the process does not cause any hard errors while the VioSavRe 
drawWait thread is running; otherwise a system lockout may occur. 


An application’s VioSavRedrawWait thread may be notified to perform a re- 
store before it is notified to perform a save. This happens if the application 
was running in the background the first time it issued VioSavRedrawWait. 
The return from this function call provides the notification. The thread that 
issues the call performs the save or redraw and then reissues VioSavRe 
drawWait to wait until its screen image must be saved or redrawn again. 
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VioScrLock (FAPI, xWPM) 


Description 
This call requests ownership of (locks) the physical display buffer. 


define INCL_VIO 
4Hinclude <os2.h> 


USHORT VioScrLock (USHORT fWait, PUCHAR pfNotLocked, HVIO hvio); 


fWait (USHORT) - input 
Indicates whether the process should block until the screen I/O can 
take place. 


Value Definition 
O Return if screen I/O not available 
({(Wait == VP_NOWAIT) 
1 Wait until screen I/O is available 
(f(Wait == VP_WAIT) 


pfNotLocked (PUCHAR) - output 
Address of the Indicator of whether the lock is successful, described here. 


Value Definition 
O Lock successful 
(*pfNotLocked == LOCK_SUCCESS) 
1 Lock unsuccessful (in the case of no wait) 
(*pfNotLocked == LOCK_FAIL) 


Status is returned only when AX = O. 


Status = 1 may be returned only when WaitFlag = O. 


hvio (HVIO) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
366 ERROR_VIO_WAIT_FLAG 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
434 ERROR_VIO_LOCK 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
494. ERROR_VIO_EXTENDED_SG 
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Remarks 


This function call permits a process to determine if I/O to the physical 
screen buffer can take place. This prevents the process from writing to the 
physical buffer when the process is in the background. Processes must co- 
operate with the system in coordinating screen accesses. 


Screen switching is disabled while the screen lock is in place. If a screen 
switch is suspended by a screen lock, and if the application holding the 
lock does not issue VioScrUnLock within a system-defined time limit, 
the screen switch occurs, and the process holding the lock is frozen in the 
background. A process should yield the screen lock as soon as possible to 
avoid being frozen when running in the background. The timeout on the 
lock does not begin until a screen switch is requested. 


When the screen lock is in effect and another thread in the same or differ- 
ent process (in the same session) issues VioScrLock, the second thread re- 
ceives an error code. VioScrUnLock must be issued by a thread within the 
same process that issued VioScrLock. 


Family API considerations 


Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following restriction applies to VioScrLock when coding in 
the DOS mode: 


The status always indicates the lock is successful (Return code = 0). 
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VioScrollIDn (FAPI) 


Description 


This call scrolls the entire display buffer (or area specified within the dis- 
play buffer) down. 


ftdefine INCL_VIO 
-Finclude <os2z.h> 


USHORT VioScrol1Dn (USHORT usTopRow, USHORT usLeftCol, 
USHORT usBotRow, USHORT usRightCol, 
USHORT cbLines, PBYTE pCell, HVIO hvio); 


usTopRow (USHORT) - input 
Top row to be scrolled. 


usLeftCol (USHORT) - input 
Left column to be scrolled. 


usBotRow (USHORT) - input 
Bottom row to be scrolled. 


usRightCol (CUSHORT) - input 
Right column to be scrolled. 


cbLines (USHORT) - input 
Number of lines to be inserted at the top of the screen area being 
scrolled. If O is specified, no lines are scrolled. 


pCell (PBYTE) - input 
Address of the character-attribute(s) pair (2 or 4 bytes) used as a fill 
character on inserted lines. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
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Remarks 
TopRow = O and LeftCol = O identifies the top left corner of the screen. 


If a value greater than the maximum value is specified for TopRow, LeftCol, 
BotRow, RightCol, or Lines, the maximum value for that parameter is used. 


If TopRow and LeftCol =O and if BotRow, RightCol, and Lines = 65535 (or 
—1 in assembler language), the entire screen is filled with the character-at- 


tribute pair defined by Cell. 
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VioScrollLf (FAPI) 


Description 


This call scrolls the entire display buffer (or area specified within the dis- 
play buffer) to the left. 


4tdefine INCL_VIO 
#include <os2.h> 


USHORT VioScrollLf (USHORT usTopRow, USHORT usLeftCol, 
USHORT usBotRow, USHORT usRightCol, 
USHORT cbCol, PBYTE pCell, HVIO hvio); 


usTopRow (USHORT) - input 
Top row to be scrolled. 


usLeftCol (USHORT) - input 
Left column to be scrolled. 


usBotRow (USHORT) - input 
Bottom row to be scrolled. 


usRightCol (USHORT) - input 
Right column to be scrolled. 


cbLines (USHORT) - input 
Number of columns to be inserted at the right of the screen area being 
scrolled. If O is specified, no lines are scrolled. 


pCell (PBYTE) - input 
Address of the character attribute(s) pair (2 or 4 bytes) used as a fill 
character on inserted columns. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
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Remarks 
TopRow = O and LeftCol = O identifies the top left corner of the screen. 


If a value greater than the maximum value is specified for TopRow, LeftCol, 
BotRow, RightCol, or Lines, the maximum value for that parameter is used. 


If TopRow and LeftCol = O and if BotRow, RightCol, and Lines = 65535 (or 
—] in assembler language), the entire screen is filled with the character-at- 
tribute pair defined by Cell. 
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~ VioScrollRt (FAPI) 


Description 


This call scrolls the entire display buffer (or area specified within the dis- 
play buffer) to the right. 


define INCL_VIO 
#include <os2.h> 


USHORT VioScrollRt (USHORT usTopRow, USHORT usLeftCol, 
USHORT usBotRow, USHORT usRightCol, 
USHORT cbCol, PBYTE pCell, HVIO hvio); 


usTopRow (USHORT) - input 
Top row to be scrolled. 


usLeftCol (USHORT) - input 
Left column to be scrolled. 


usBotRow (USHORT) - input 
Bottom row to be scrolled. 


usRightCol (USHORT) - input 
Right column to be scrolled. 


cbCol (USHORT) - input 
Number of columns to be inserted at the left of the screen area being 
scrolled. If O is specified, no lines are scrolled. 


pCell (PBYTE) - input 
Address of the character attribute(s) pair (2 or 4 bytes) used as a fill 
character on inserted columns. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
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Remarks 
TopRow = O and LeftCol = O identifies the top left corner of the screen. 


If a value greater than the maximum value is specified for TopRow, LeftCol, 
BotRow, RightCol, or Lines, the maximum value for that parameter is used. 


If TopRow and LeftCol = O and if BotRow, RightCol, and Lines = 65535 (or 
—1 in assembler language), the entire screen is filled with the character-at- 


tribute pair defined by Cell. 
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VioScrollUp (FAPI) 


Description 


This call scrolls the entire display buffer (or area specified within the dis- 
play buffer) up. 


4define INCL_VIO 
include <os2.h> 


USHORT VioScrollUp (USHORT usTopRow, USHORT usLeftCol, 
USHORT usBotRow, USHORT usRightCol, 
USHORT cbLines, PBYTE pCell, HVIO hvio); 


usTopRow (USHORT) - input 
Top row to be scrolled. 


usLeftCol (USHORT) - input 
Left column to be scrolled. 


usBotRow (USHORT) - input 
Bottom row to be scrolled. 


usRightCol (USHORT) - input 
Right column to be scrolled. 


cbLines (USHORT) - input 
Number of lines to be inserted at the bottom of the screen area being 
scrolled. If O is specified, no lines are scrolled. 


pCell (PBYTE) - input 
Address of the character attribute(s) pair (2 or 4 bytes) used as a fill 
character on inserted lines. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
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Remarks | 
TopRow = O and LeftCol = 0 identifies the top left corner of the screen. 


If a value greater than the maximum value is specified for TopRow, LeftCol, 
BotRow, RightCol, or Lines, the maximum value for that parameter is used. 


If TopRow and LeftCol = O and if BotRow, RightCol, and Lines = 65535 (or 
—1 in assembler language), the entire screen is filled with the character-at- 
tribute pair defined by Cell. 
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VioScrUnLock (FAPI, xWPM) 


Description 
This call releases ownership of (unlocks) the physical display buffer. 


4tdefine INCL_VIO 
#Finclude <os2.h> 


USHORT VioScrUnLock (HVIO hvio); 


hvio (HVIO) - input 
Reserved word of Os. 


Return value 


OQ NO_ERROR 
367 ERROR_VIO_UNLOCK 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
494 ERROR_VIO_EXTENDED_SG 


Remarks 


This call releases the screen lock that is set by Vi oScrLock. The VioScrUnLock 
call must be issued by a thread in the same process as the thread that is- 
sued VioScrLock. 


Family API considerations 


Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following restriction applies to VioScrUnLock when coding in 
the DOS mode: 


The status always indicates the unlock is successful (return code = 0). 
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VioSetAnsi (xPM) 


Description 
This call activates or deactivates ANSI support. 


define INCL_VIO 
#Finclude <os2.h> 


USHORT VioSetAnsi (USHORT fAnsi, HVIO hvio);: 


fAnsi (USHORT) - input 
Equals 1 to activate ANSI support (fAnsi == ANSI_ON) or O (fAnsi == 
ANSI OFF) to deactivate ANSI. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
421 ERROR_VIO_INVALID_PARMS 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 
For ANSI support, “ON” is the default. 
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VioSetCp (xPM) 


Description 


This call allows a process to set the code page used to display text data on 
the screen for the specified handle. 


define INCL_VIO 
#Finclude <os2.h> 


USHORT VioSetCp (USHORT usReserved, USHORT idCodePage, HVIO hvio); 


usReserved (USHORT) - input 
Reserved word of Os. 


idCodePage (USHORT) - input 

The CodePageID must be either O, —1, —2, or have been specified on the 
CONFIG.SYS CODEPAGE = statement. A value of 0000 indicates that 
the code page is to be set to the default ROM code page provided by the 
hardware. A value of —1 enables the user font codepage if user fonts 
have previously been set with VioSetFont. A value of —2 disables the 
user font and re-enables the prepared system codepage or ROM code- 
page that was active before the user font was enabled. 


If the code page ID is not O, —1, —2, or does not match one of the IDs on 
the CODEPAGE = statement, an error results. Refer to IBM Operating Sys- 
tem/2.0 Command Reference for a complete description of CODEPAGE. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 
469 ERROR_VIO_BAD_CP 
470 ERROR_VIO_NO_CP 
471 ERROR_VIO_NA_CP 


Remarks 


VioSetCp can be used to enable and disable the user font code page as well 
as the prepared system code pages. If a prepared system code page or the 
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ROM code page is specified, any previously set code page is disabled and 
the specified code page is enabled. 


Specifying the special code page of —1 enables the user font code page if user 
fonts have previously been set. Specifying the special code page of —2 disables 
the user font code page and re-enables the prepared system code page or 
ROM code page that was active before the user font code page was enabled. 


PM considerations 


Valid CodePageID values are either O or one that was specified on the 
CONFIG.SYS CODEPAGE = statement; —1 and —2 are not valid for PM. 


This call can be used to set an EBCDIC code page for Advanced VIO. Fora 
full-screen or Vio-windowed application, this function causes the dis- 
played characters to be reinterpreted immediately in the new code page. 
For a Presentation Manager application, the characters in the base font 
are reinterpreted in the new code page only when other events cause the 
characters to be repainted. This function has no effect on displayed char- 
acters that use a font other than the base font. 
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VioSetCurPos (FAPI) 


Description 


This call sets the cursor’s coordinates on the screen. 


4tdefine INCL_VIO 
#Finclude <os2.h> 


USHORT VioSetCurPos (USHORT usRow, USHORT usColumn, HVIO hvio); 


usRow (USHORT) - input 
New cursor row position, O is the top row. 


usColumn (USHORT) - input 
New cursor column position, O is the leftmost column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_ HANDLE 
465 ERROR_VIO_DETACHED 
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VioSetCurType (FAPI) 


Description 
This call sets the cursor type. 


#define INCL_VIO 
d#Finclude <os2.h> 


USHORT VioSetCurType (PVIOCURSORINFO pvioCursorInfo, HVIO hvio); 


pvioCursorInfo (PVIOCURSORINFO) - input 
Address of the cursor characteristics structure: 


yStart (USHORT ) 
Horizontal scan line in the character cell that marks the top line of 
the cursor. If the character cell has n scan lines, O is the top scan 
line of the character cell and (n — 1) is the bottom scan line. 


cEnd (USHORT) 
Horizontal scan line in the character cell that marks the bottom 
line of the cursor. Scan lines within a character cell are numbered 
as defined in startline. The maximum value allowed is 31. 


cx (CUSHORT ) 
Width of the cursor. In text modes, cursorwidth is the number of 
columns. The maximum number supported by the OS/2 base video 
subsystem is 1. In graphics modes, cursorwidth is the number of pels. 


A value of O specifies the default width. In text modes, this is 1 col- 
umn. In graphics modes, this is the number of pels equivalent to 
the width of one character. 


attr (USHORT) 
A value of —1 denotes a hidden cursor, all other values denote a 
normal cursor. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager ap- 
plication, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
356 ERROR_VIO_WIDTH 
421 ERROR_VIO_INVALID_PARMS 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


142 Video (VIO) functions 


Remarks 

To set CursorStartLine and CursorEndLine independent of the number of 
scan lines for each character cell, you may specify these parameters as per- 
centages. OS/2 then calculates the physical start and end scan lines, re- 
spectively, by multiplying the percentage specified for the parameter by the 
total number of scan lines in the character cell and rounding to the nearest 
scan line. Percentages are specified as negative values (or O) in the range O 
through —100. Specifying CursorStartLine =—90 and CursorEndLine =—100 
requests a cursor that occupies the bottom 10 percent of the character cell. 


PM considerations 


Set the cursor type. The cursor type consists of the cursor start line, end line, 
width (assumed O - one column width) and attribute (normal or hidden). 
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VioSetFont (FAPI, xWPM) 


Description 
This call downloads a display font. The font being set must be compatible 
with the current mode. 


4edefine INCL_VIO 
#Finclude <os2.h> 


USHORT VioSetFont (PVIOFONTINFO pviofi, HVIO hvio); 


pviofi (PVIOFONTINFO) - input 
Address of the font structure containing the request: 


cb (USHORT) 
Length of structure, including cb. 


14 Only valid value. 


type (USHORT) 
Request type: 
Type Definition 
O Set current RAM font for EGA, VGA, or IBM Personal Sys- 
tem/2 Display Adapter. 


cxCell (USHORT) 
Pel columns in character cell. 


cyCell (USHORT) 
Pel rows in character cell. 


pbData (PVOID) 
Address of the data area containing font table to set. 


cbData (USHORT ) 
Length, in bytes, of the caller-supplied data area; must be 256 
times the character cell height specified in pelrows. 


hvio (HVIO) - input 
Reserved word of Os. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
421 ERROR_VIO_INVALID_PARMS 
436 ERROR_VIO_INVALID_HANDLE 
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438 ERROR_VIO_INVALID_LENGTH 
465 ERROR_VIO_DETACHED 

467 ERROR_VIO_FONT 

468 ERROR_VIO_USER_FONT 

494 ERROR_VIO_EXTENDED_SG 


Remarks 


VioSetFont is applicable only for the enhanced graphics adapter, VGA or 
IBM Personal System/2 Display Adapter. 


Note Although graphics mode support is provided in VioSetFont, this 
support is not provided by the Base Video Handlers provided with OS/2. 


When VioSetFont is issued, the current code page is reset. If VioGetCp is 
subsequently issued, the error code ERROR_VIO_USER_FONT is re- 
turned. Return code, ERROR_VIO_USER_FONT represents a warning. It 
indicates that although the font could not be loaded into the adapter us- 
ing the current mode, the font was saved as part of a special user font code 
page for use with a later VioSetMode. Successfully setting a user font sets 
the special user font code page, just as if a code page of —1 was specified 
using VioSetCp. 


The user font code page consists of the most recent user font of each size 
that was set by VioSetFont. For example, if two 8x12 fonts and three 8x16 
fonts had been set, only two fonts, the most recent of the 8x12 and 8x16 
fonts, would be saved. 


The special code page is used in the same way as those code pages speci- 
fied on the CODEPAGE = statement in CONFIG.SYS. 
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VioSetMode (FAPI, xPM) 


Description 
This call sets the mode of the display. 


define INCL_VIO 
d#Finclude <os2.h> 


USHORT VioSetMode (PVIOMODEINFO pvioModeInfo, HVIO hvio); 


pvioModeInfo (PVIOMODEINFO) - input 
Address of the mode characteristics structure: 


cb (USHORT) 
Input parameter to VioSetMode. Length specifies the cb of the data 
structure in bytes including Length itself. The minimum structure 
size required is 3 bytes. OS/2 sets to the first mode (in the list of 
modes supported by this display configuration) with a data struc- 
ture matching the mode data specified. 


fbType (UCHAR) 
Mode characteristics bit mask: 


Bit Description 


7-4 Reserved, set to zero. 
3 O = VGA-compatible modes O thru 13H. 
1 = Native mode. 
2 O = Enable color burst 
'(fbType & VGMT_DISABLEBURST) 
1 = Disable color burst 
(fbType & VGMT_DISABLEBURST) 
1 O = Text mode 
'(fbType & VGMT_GRAPHICS) 
1 = Graphics mode 
(fbType & VGMT_GRAPHICS) 
O O = Monochrome compatible mode 
!(fobType & VGMT_OTHER) 
1 = Other. 
(fbType & VGMT_OTHER) 


color (UCHAR) 
Number of colors defined as a power of 2. This is equivalent to the 
number of color bits that define the color, for example: 
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Value Definition 
O Monochrome modes 7, 7+, and F. 
1 2. colors. 
2 4 colors. 
4 16 colors. 
8 256 colors. 


col (USHORT ) 
Number of text columns. 


row (USHORT ) 
Number of text rows. 


hres (USHORT) 
Horizontal resolution, number of pel columns. 


vres (USHORT) 
Vertical resolution, number of pel rows. 


fmt_ID (UCHAR) 
Identifies the format of the attributes. 


attrib (UCHAR) 
Identifies the number of attributes in a character cell. 


buf_addr (ULONG) 
32-bit physical address of the physical display buffer for this mode. 


buf_length (ULONG) 
Length of the physical display buffer for this mode. 


full_length (ULONG) 
Size of the buffer required for a full save of the physical display 
buffer for this mode. 


partial_length (ULONG) 
Size of the buffer required for a partial (pop-up) save of the physi- 
cal display buffer for this mode. 


ext_data_addr (PCH) 
Far address to an extended mode data structure or zero if none. 
The format of the extended mode data structure is determined by 
the device driver and is unknown to OS/2. 


hvio (HVIQ) - input 
Reserved word of Os. 
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Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
436 ERROR_VIO_INVALID_HANDLE 
438 ERROR_VIO_INVALID_LENGTH 
465 ERROR_VIO_DETACHED 
467 ERROR_VIO_FONT 
468 ERROR_VIO_USER_FONT 
494 ERROR_VIO_EXTENDED_SG 


Remarks 


VioSetMode initializes the cursor position and type. 


VioSetMode does not clear the screen. To clear the screen, use one of the 
VioScrollxx calls. 


The disable color burst bit in the Type field in the VioSetMode data struc- 
ture is functional only for the CGA and VGA. This bit causes the color 
portion of the video signal to be suppressed, producing a black and white 
mode on composite monitors attached to the CGA. On VGA, the bit 
causes the color lookup table to be loaded with values that produce 
shades of gray instead of colors, again producing a black and white mode. 
For all other combinations of adapters and displays, the setting of this bit 
is recorded and returned on any subsequent VioGetMode call, but other- 
wise is ignored. 


For text modes in full-screen sessions, the number of rows on the screen 
is determined by the availability of fonts of the correct size. For any speci- 
fied mode, the size of the character defined by the font must be (Horizon- 
tal Resolution) /(Text Columns) dots wide and (Vertical Resolution) /(Text 
Rows) dots high. For example, an 8x8 font would support 39 through 43 
text rows if the screen resolution were 640x350. 


If VioSetState request type 6 has been issued previously to select the tar- 
get display configuration for VioSetMode, the mode is set on the display 
configuration selected. If that display configuration does not support the 
mode specified, an error is returned. 


Assuming no target display configuration for VioSetMode is selected, the 
mode is set on the primary configuration. If the primary configuration 
does not support the mode specified, the mode is set on the secondary 
configuration. 


The table below shows the VioSetMode parameters required to set all the 
modes supported by the CGA, EGA, VGA, and PS/2 Display Adapters. The 
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modes native to the 8514/A and other advanced video adapters are set with 
the Adapter (programming) Interface to these adapters, not Vi oSetMode. 


Note Although graphics mode support is provided in VioSetMode, this 
support is not provided by the Base Video Handlers provided with 


OS/2. 


Table 3-2 Display mode attributes supported by adapters 


Bios 
mode Type Color ColS Rows Hres 


O 5 4 40 25 320 
Ox 5 4 40 25 320 
O+ 5 4 40 25 360 
OF 5 a 40 25 320 
] 1 4 40 25 320 
1* 1 4 40 25 320 
1+ i 4 40 25 360 
1# 1 4 40 25 320 
2 5 4 80 25 640 
2% 5 4 80 209 640 
Zt 5 ae 80 25 720 
2H 5 4 80 25 640 
3 ] 4 80 25 640 
3* 1 4 80 25 640 


Vres 


200 


350 


400 
400 


200 


350 


400 
400 


200 


350 


400 
400 


200 


350 


Valid adapter/display 
combinations [emulated] 


[CGA/CD],CGA/Comp, 
[EGA/CD], [EGA/ECD], 
VGA/Mono, VGA/Color, 
VGA Plasma 


[EGA/ECD], VGA/Mono, 
VGA/Color, VGA/Plasma 


VGA/Mono, VGA/Color 


VGA/Mono, VGA/Color, 
VGA/Plasma 


CGA/CD, CGA/Comp, 
EGA/CD, EGA/ECD, 
[VGA/Mono], VGA/Color, 
[VGA Plasma] 


EGA/ECD, [VGA/Mono], 
VGA/Color, [VGA/Plasma] 


[VGA/Mono], VGA/Color, 


[VGA/Mono], VGA/Color, 
[VGA Plasma] 


[CGA/CD], CGA/Comp, 
[EGA/CD], [EGA/ECD], 
VGA/Mono, VGA/Color, 
VGA Plasma 


[EGA/ECD], VGA/Mono, 
VGA/Color, VGA/Plasma 


VGA/Mono, VGA/Color 


VGA/Mono, VGA/Color, 
VGA/Plasma 


CGA/CD, CGA/Comp, 
EGA/CD, EGA/ECD, 
[VGA/Mono], VGA/Color, 
[VGA, Plasma] 


EGA/ECD, [VGA/Mono], 
VGA/Color, [VGA,Plasma] 
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Table 3-2 Continued 


Bios Valid adapter/display 
mode Type Color ColS Rows Hres Vres combinations [emulated] 
3+ 1 4 80 25 720 400 [VGA/Mono], VGA/Color 
3# 1 4 80 25 640 400 [VGA/Mono], VGA/Color, 
[VGA/Plasma] 

7 O 0 80 25 720 350 MPA/MD, EGA/MD, 
VGA/Mono, VGA/Color 

7+ O O 80 25 720 400 VGA/Mono, VGA/Color 

7# O O 80 25 640 400 VGA/Mono, VGA/Color, 
VGA/Plasma 

n/a 0 0 80 25 640 350 VGA/Mono, VGA/Color, 
VGA/Plasma 

n/a 1 4 80 30 720 480 [VGA/Mono], VGA/Color 

n/a 1 4 80 30 640 480 [VGA/Mono], VGA/Color, 
VGA/Plasma 

4 3 2 [40] [25] 320 200 CGA/CD, CGA/Comp, 


EGA/CD, EGA/ECD, 
[VGA/Mono], VGA/Color, 
[VGA/Plasma] 


5 7 2 [40] [25] 320 200 [CGA/CD], CGA/Comp, 
[EGA/CD], [EGA/ECD], 
VGA/Mono, VGA/Color, 
VGA/Plasma 


6 3 1 [80] [25] 640 200 CGA/CD, CGA/Comp, 
EGA/CD, EGA/ECD, 
VGA/Mono, VGA/Color, 
VGA/Plasma 


D 3 4 [40] [25] 320 200 EGA/CD, EGA/ECD, 
[VGA/Mono], VGA/Color, 
[VGA/Plasma] 


E 2 4 [80] [25] 640 200 EGA/CD, EGA/ECD, 
[VGA/Mono], VGA/Color, 
[VGA/Plasma] 


F 2 O [80] [25] 640 350 EGA/MD, VGA/Mono, 
VGA/Color, VGA/Plasma 


10 3 4 [80] [25] 640 350 EGA/ECD, [VGA/Mono], 
VGA/Color, [VGA/Plasma] 


ll 3 1 [80] [30] 640 480 VGA/Mono, VGA/Color, 
VGA/Plasma 


12 3 4 [80] [30] 640 480 [VGA/Mono], VGA/Color, 
[VGA/Plasma] 
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13 3 8 [40] [25] 320 200 [VGA/Mono], VGA/Color, [VGA/Plasma] 
n/a ll 8 [80] [80] 640 480 [8514A/Mono], 8514A/Color 

n/a ll 4 [80] [380] 640 480 [8514A/Mono], 8514A/Color 

n/a 11 8 [85] [88] 1024 768 [8514A/HMono], 8514A/HColor 

n/a ll 4 [85] [88] 1024 768 [8514A/HMono], 8514A/HColor 


Display adapters 


MPA Monochrome/Printer Adapter 

CGA Color Graphics Adapter 

EGA Enhanced Graphics Adapter 

VGA __~-Video Graphics Array, PS/2 Display Adapter 
8514A 8514A Display Adapter 


Displays 

MD 5151 Monochrome Display 
CD 5153 Color Display 

ECD 5154 Enhanced Color Display 


MONO 8503 PS/2 Monochrome Display, 8507/8604 Display 
HMONO- 8507/8604 Display 

COLOR 8512/13 PS/2 Color Display, 8514 Display 

HCOLOR 8514/Display 

PLASMA Plasma Display Panel 

COMP Composite Video Monitor 


Notes 
Types O, 1, and 5 are text modes; types 2, 3, 7 and 11 are graphics modes. 
For BIOS mode, 0, 2, 5, the color burst is disabled on the CGA and VGA. 


The Personal System/2 Display Adapter 8514/A (TM) has advanced function 
modes, which are supported through the 8514/A display adapter interface, not 
the VIO Subsystem. Refer to the Personal System/2 Display Adapter 8514/A 
Technical Reference for details of this support. 


For text modes in full-screen, the number of rows might differ from the mode 
table due to the availability of fonts of the correct size as described earlier. 


PM considerations 


Windowable VIO sessions support only 80-column, color text modes. 
When VioSetMode is called from a Windowable VIO session, it only verifies 
that an 80-column text mode was requested, with Text Rows between 1 
and 255. The resulting mode, which can be queried using VioGetMode, al- 
ways has Type = 1, Color = 4, Text Columns = 80, Text Rows = requested 
Text Rows, Horizontal Resolution = 640, and Vertical Resolution = 16 * 
(Text Rows). 
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Family API considerations 

Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following consideration applies to VioSetMode when coding 
for the DOS mode: 


VioSetMode clears the screen. 
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VioSetState (FAPI, xWPM) 


Description 


This call performs one of the following functions; set palette registers, sets 
the overscan (border) color, set the blink/background intensity switch, set 
color registers, set the underline location, or set the target Vi oSetMode dis- 
play configuration. 


4edefine INCL_VIO 
4#Ainclude <os2.h> 


USHORT VioSetState (PVOID pState, HVIO hvio); 


pState (PVOID) - input 
Address of one of six different state structures, depending on the re- 
quest type. The request type is the second word of the packet. 


Type Definition 

Set palette registers 

Set overscan (border) color 

Set blink/background intensity switch 

Set color registers 

Reserved 

Set underline location 

Set target VioSetMode display configuration 
Reserved 


NQOOUPWNF © 


The six structures, depending on request type, are as follows: 


VIOPALSTATE 
Applies to EGA, VGA, or IBM Personal System/2 Display Adapter. 


cb (USHORT) - input 
Length of structure, including cb. 


38 Maximum valid value. 


type (USHORT) - input 
Request type O for palette registers. 


iFirst (USHORT) - input 
First palette register in the palette register sequence; must be spec- 
ified in the range O through 15. The palette registers are returned 
in sequential order. The number returned is based upon cb. 


acolor (USHORTL(cb-6)/2]) - input 
Color value for each palette register. The maximum number of en- 
tries in the color value array is 16. 
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VIOOVERSCAN 
Applies to CGA, VGA, or IBM Personal System/2 Display Adapter. 
cb (USHORT) - input 

Length of structure, including cb. 

6 Only valid value. 


type (USHORT) - input 
Request type 1 for overscan (border) color. 


color (USHORT) - input 
Color value. 


VIOINTENSITY 


Applies to CGA, EGA, MCGA, VGA, or IBM Personal System/2 Display 
Adapter. 


cb (USHORT) - input 
Length of structure, including cb. 


6 Only valid value. 


type (USHORT) - input 
Request type 2 for blink/background intensity switch. 


fs (USHORT) - input 
Switch set as: 
Value Definition 


QO Blinking foreground colors enabled. 
1 High intensity background colors enabled. 


VIOCOLORREG 
Applies to VGA, or IBM Personal System/2 Display Adapter. 


cb (USHORT) - input 
Length of structure, including cb. 


12 Only valid value. 


type (USHORT) - input 
Request type 3 for color registers. 


firstcolorreg (USHORT) - input 
First color register to set in the color register sequence; must be 
specified in the range O through 255. The color registers are set in 
sequential order. 


numcolorregs (USHORT) - input 
Number of color registers to set; must be specified in the range 1 
through 256. 


colorregaddr (PCH) - input 
Far address of a data area containing one three-byte entry for each 
color register to be set. The format of each entry is as follows: 
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Byte 1 Red value 
Byte 2. Green value 
Byte 3 Blue value. 


VIOSETULINELOC 
Applies to EGA, VGA, or IBM Personal System/2 Display Adapter. 


cb (USHORT) - input 
Length of structure, including cb. 


6 Only valid value. 


type (USHORT) - input 
Request type 5 to set the scan line for underlining. Underlining is 
enabled only when the foreground color is 1 or 9. 


scanline (USHORT) - input 
Scan line minus 1. Values of O through 31 are acceptable. A value 
of 32 means underlining is disabled. 


VIOSETTARGET 


cb (USHORT) - input 
Length of structure, including cb. 


6 Only valid value. 


type (USHORT) - input 
Request type 6 to set display configuration to be the target of the 
next VioSetMode. 


defaultalgorithm (USHORT) - input 
Configuration: 
Value Definition 
O Default selection algorithm. See VioSetMode. 
(defaultalgorithm == VIO_CONFIG_CURRENT) 
1 Primary 
(defaultalgorithm == VIO_CONFIG_PRIMARY) 
2 Secondary. 
(defaultalgorithm == VIO_CONFIG_SECONDARY) 


hvio (HVIO) - input 
Reserved word of Os. 


Return value 


O 
355 
421 
436 
438 
465 
494 


NO_ERROR 
ERROR_VIO_MODE 
ERROR_VIO_INVALID_PARMS 
ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_INVALID_LENGTH 
ERROR_VIO_DETACHED 
ERROR_VIO_EXTENDED_SG 
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Family API considerations 


Request type = 6, Set Target Vi oSetMode Display Configuration, and request 
type = 5, Set Underline Location, are not supported in the Family API. 


Some options operate differently in the DOS mode than in the OS/2 mode. 
Therefore, the following considerations applies to VioSetMode when coding 
for the DOS mode: 


VioSetMode clears the screen. 
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VioShowBuf (xPM) 


Description 
This call updates the physical display buffer with the logical video buffer 
(LVB). 


##define INCL_VIO 
##include <os2.h> 


USHORT VioShowBuf CUSHORT offLVB, USHORT cb, HVIO hvio); 


offLVB (USHORT) - input 
Starting offset within the logical video buffer at which the update to the 
screen is to start. 


cb (USHORT) - input 
Length of the area to be updated to the screen. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


OQ NO_ERROR 
355 ERROR_VIO_MODE 
430 ERROR_VIO_ILLEGAL_DURING_POPUP 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


VioShowBuf is ignored unless it is issued by a process that has previously 
called VioGetBuf and that is currently executing in the foreground. 


PM considerations 
This function updates the display with the Advanced VIO presentation space. 
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VioWrtCellStr (FAPI) 


Description 
This call writes a string of character-attribute pairs (cells) to the display. 


+#define INCL_VIO 
#Finclude <os2.h> 


USHORT VioWrtCel1Str (PCH pchCellStr, USHORT cb, 
USHORT usRow, USHORT usColumn, HVIO hvio); 


pchCel|lStr (PCH) - input 
Address of the string of character-attribute(s) cells to be written. 


cb (USHORT) - input 
Length, in bytes, of the string to be written. Each character-attribute(s) 
cell is 2 or 4 bytes. 


usRow (USHORT) - input 
Starting cursor row. 


usColumn (USHORT) - input 
Starting cursor column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a string write gets to the end of the line and is not complete, the string 
write continues at the beginning of the next line. If the write gets to the end 
of the screen, the write terminates. 


PM considerations 


Write a character-attribute string to the Advanced VIO presentation space. 
The caller must specify the starting location on the presentation space 
where the string is to be written. 
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VioWrtCharStr (FAPI) 


Description 
This call writes a character string to the display. 


define INCL_VIO 
F7include <asZ,h> 


USHORT VioWrtCharStrAtt (PCH pch, USHORT cb, 
USHORT usRow, USHORT usColumn, 
PBYTE pAttr, HVIO hvio); 


pch (PCH) - input 
Address of the character string to be written. 


cb (USHORT) - input 
Length, in bytes, of the character string. 


usRow (USHORT) - input 
Starting cursor row. 


usColumn (USHORT) - input 
Starting cursor column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a string write gets to the end of the line and is not complete, the string 
write continues at the beginning of the next line. If the write gets to the end 
of the screen, the write terminates. 


PM considerations 


Write a character string to the Advanced VIO presentation space. The 
caller must specify the starting location on the presentation space where 
the string is to be written. 
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VioWrtCharStrAtt (FAPI) 


Description 


This call writes a character string with repeated attribute to the display. 


4edefine INCL_VIO 
d#Finclude <os2.h> 


USHORT VioWrtCharStrAtt (PCH pch, USHORT cb, USHORT usRow, 
USHORT usColumn, PBYTE pAttr, HVIO hvio); 


pch (PCH) - input 
Address of the character string to be written. 


cb (USHORT) - input 
Length, in bytes, of the character string. 


usRow (USHORT) - input 
Starting cursor row. 


usColumn (USHORT) - input 
Starting cursor column. 


pAttr (PBYTE) - input 
Address of the attribute(s) (1 or 3 bytes) to be used in the display buffer 
for each character of the string written. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a string write gets to the end of the line and is not complete, the string 
write continues at the beginning of the next line. If the write gets to the end 
of the screen, the write terminates. 
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PM considerations 
Write a character string with a repeated attribute string to the Advanced 


VIO presentation space. The caller must specify the starting location on 
the presentation space where the string is to be written. 
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VioWrtNAttr (FAPI) 


Description 


This call writes an attribute to the display a specified number of times. 


4edefine INCL_VIO 
#include <os2.h> 


USHORT VioWrtNAttr (PBYTE pAttr, USHORT cb, USHORT usRow, 
USHORT usColumn, HVIO hvio); 


pAttr (PBYTE) - input 
Address of the attribute(s) (1 or 3 bytes) to be written. 


cb (USHORT) - input 
Number of times to write the attribute. 


usRow (USHORT) - input 
Starting cursor row. 


usColumn (USHORT) - input 
Starting cursor column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a repeated write gets to the end of the line and is not complete, the write 
continues at the beginning of the next line. If the write gets to the end of 
the screen, the write terminates. 


PM considerations 


Write an attribute code to the Advanced VIO presentation space a specified 
number of times. The caller must specify the starting location on the pre- 
sentation space where the string is to be written. 
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VioWrtNCell (FAPI) 


Description 


This call writes a cell (character-attribute pair) to the display a specified 
number of times. 


define INCL_VIO 
4#Finclude <os2.h> 


USHORT VioWrtNCell (PBYTE pCell, USHORT cb, 
USHORT usRow, USHORT usColumn, 
HVIO hvio); 


pCell (PBYTE) - input 
Address of the character-attribute(s) cell (2 or 4 bytes) to be written. 


cb (USHORT) - input 
Number of times to write the cell. 


usRow (USHORT) - input 
Starting cursor row. 


usColumn (USHORT) - input 
Starting cursor column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 

355 ERROR_VIO_MODE 

358  ERROR_VIO_ROW 

359 ERROR_VIO_COL 

436  ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a repeated write gets to the end of the line and is not complete, the write 
continues at the beginning of the next line. If the write gets to the end of 
the screen, the write terminates. 


PM considerations 


Write a cell (character-attribute) to the Advanced VIO presentation space a 
specified number of times. The caller must specify the starting location on 
the presentation space where the string is to be written. 


Video (VIO) functions 163 


VioWrtNChar (FAPI) 


Description 


VioWrtNChar writes a character to the display a specified number of times. 


define INCL_VIO 
4#Finclude <os2.h> 


USHORT VioWrtNChar (PCH pchChar, USHORT cb, USHORT usRow, 
USHORT usColumn, HVIO hvio); 


pchChar (PCH) - input 
Address of the character to be written. 


cb (USHORT) - input 
Number of times to write the character. 


usRow (USHORT) - input 
Starting cursor row. 


usColumn (USHORT) - input 
Starting cursor column. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 
355 ERROR_VIO_MODE 
358 ERROR_VIO_ROW 
359 ERROR_VIO_COL 
436 ERROR_VIO_INVALID_HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a repeated write gets to the end of the line and is not complete, the write 
continues at the beginning of the next line. If the write gets to the end of 
the screen, the write terminates. 


PM considerations 


Write a character to the Advanced VIO presentation space a number of 
times. The caller must specify the starting location on the presentation 
space where the string is to be written. 
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VioWrtT TY (FAPI) 


Description 


This call writes a character string to the display starting at the current 
cursor position. At the completion of the write, the cursor is positioned at 
the first position beyond the end of the string. 


define INCL_VIO 
#Finclude <os2.h> 


USHORT VioWrtTTY (PCH pch, USHORT cb, HVIO hvio); 


pch (PCH) - input 
Address of the string to be written. 


cb (USHORT) - input 
Length of the character string in bytes. 


hvio (HVIO) - input 
This must be zero unless the caller is a Presentation Manager applica- 
tion, in which case it must be the value returned by VioGetPs. 


Return value 


O NO_ERROR 

355 ERROR_VIO_MODE 

436 ERROR_VIO_INVALID_ HANDLE 
465 ERROR_VIO_DETACHED 


Remarks 


If a string write gets to the end of the line and is not complete, the string 
write continues at the beginning of the next line. If the write gets to the 
end of the screen, the screen is scrolled, and the write continues until 
completed. 


The characters carriage return, line feed, backspace, tab, and bell are 
treated as commands rather than printable characters. Backspace is a 
non-destructive backspace. Tabs are expanded to provide standard 8- 
byte-wide fields. VioWrtTTY is the only video call affected by Ctrl-PrtSc 
and ANSI. 


Characters are written using the current attribute defined by ANSI or the 
default value 7. 


Video (VIO) functions 165 


VioWrtTTY is supported in graphics mode to process ANSI sequences. This 
allows the application to enter and exit a graphics mode. 


PM considerations 


Write a character string from the current cursor position in TTY mode to 
the Advanced VIO presentation space. The cursor is positioned after the 
last character written at the end of the write. 
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Errors returned 


from base 
OS/2 calls 


This appendix contains the error number, name, and description of the er- 
rors returned from the KBD/MOU/VIO calls. 


O 


10 


11 


12 


13 


14 
15 


16 


17 


NO_ERROR 
No error occurred. 


ERROR INVALID FUNCTION 
Invalid function number. 


ERROR FILE _NOT_FOUND 
File not found. 


ERROR_PATH NOT FOUND 
Path not found. 


ERROR_TOO_MANY_OPEN_FILES 
Too many open files (no handles left). 


ERROR _ ACCESS_DENIED 
Access denied. 


ERROR _ INVALID. HANDLE 
Invalid handle. 


ERROR_ARENA_TRASHED 
Memory control blocks destroyed. 


ERROR_NOT_ENOUGH_MEMORY 
Insufficient memory. 


ERROR_INVALID_BLOCK 
Invalid memory-block address. 


ERROR _ BAD ENVIRONMENT 
Invalid environment. 


ERROR _ BAD FORMAT 
Invalid format. 


ERROR _INVALID_ACCESS 
Invalid access code. 


ERROR_INVALID_DATA 
Invalid data. 


Reserved. 


ERROR_INVALID_DRIVE 
Invalid drive specified. 


ERROR_CURRENT_DIRECTORY 
Attempting to remove current directory. 


ERROR NOT _SAME_ DEVICE 
Not same device. 
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18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


30 


31 


32 


33 


34 


35 


36 


ERROR _NO MORE FILES 
No more files. 


ERROR_WRITE_PROTECT 
Attempt to write on write-protected diskette. 


ERROR _BAD_ UNIT 
Unknown unit. 


ERROR_NOT_READY 
Drive not ready. 


ERROR BAD COMMAND 
Unknown command. 


ERROR_CRC 
Data error (CRC). 


ERROR_BAD_LENGTH 
Bad request structure length. 


ERROR SEEK 
Seek error. 


ERROR_NOT_DOS_DISK 
Unknown media type. 


ERROR_SECTOR_NOT FOUND 
Sector not found. 


ERROR_OUT_OF_PAPER 
Printer out of paper. 


ERROR_WRITE_ FAULT 
Write fault. 


ERROR READ FAULT 
Read fault. 


ERROR _GEN_FAILURE 
General failure. 


ERROR_SHARING_VIOLATION 
Sharing violation. 


ERROR_LOCK_ VIOLATION 
Lock violation. 


ERROR_WRONG_DISK 
Invalid disk change. 


ERROR FCB UNAVAILABLE 
FCB unavailable. 


ERROR_SHARING_BUFFER_EXCEEDED 
Sharing buffer overflow. 
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37-49 
50 


65 
73-79 
80 


81 


82 


83 


84 


85 


86 


87 


88 


89 


90 


91 


92 


93 


95 


99 


Reserved. 


ERROR_NOT_SUPPORTED 
Network request not supported. 


Access denied. 
Reserved. 


ERROR_FILE_EXISTS 
File exists. 


ERROR _DUP_FCB 
Reserved. 


ERROR_CANNOT_MAKE 
Cannot make directory entry. 


ERROR FAIL [24 
Fail on INT 24. 


ERROR_OUT_OF_STRUCTURES 
Too many redirections. 


ERROR_ALREADY_ASSIGNED 
Duplicate redirection. 


ERROR_INVALID_PASSWORD 
Invalid password. 


ERROR_INVALID_PARAMETER 
Invalid parameter. 


ERROR _NET WRITE FAULT 
Network device fault. 


ERROR_NO_PROC_SLOTS 
No process slots available. 


ERROR_NOT_FROZEN 
System error. 


ERR_TSTOVFL 
Timer service table overflow. 


ERR_TSTDUP 
Timer service table duplicate. 


ERROR _NO_ITEMS 
No items to work on. 


ERROR_INTERRUPT 
Interrupted system call. 


ERROR_DEVICE_IN_ USE 
Device in use. 
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100 


101 


102 


103 


104 


105 


106 


107 


108 


109 


110 


112 


lis 


114 


115 


116 


117 


118 


ERROR_TOO_MANY_SEMAPHORES 
User/system open semaphore limit exceeded. 


ERROR_EXCL_SEM_ALREADY_OWNED 
Exclusive semaphore already owned. 


ERROR_SEM_IS_SET 
DosCloseSem found semaphore set. 


ERROR_TOO_MANY_SEM_REQUESTS 
Too many exclusive semaphore requests. 


ERROR_INVALID_AT_INTERRUPT_TIME 
Operation invalid at interrupt time. 


ERROR_SEM_OWNER_DIED 
Previous semaphore owner terminated without freeing semaphore. 


ERROR_SEM_USER_LIMIT 
Semaphore limit exceeded. 


ERROR_DISK_CHANGE 
Insert drive B disk into drive A. 


ERROR_DRIVE_LOCKED 
Drive locked by another process. 


ERROR_BROKEN_PIPE 
Write on pipe with no reader. 


ERROR_OPEN_FAILED 
Open/create failed due to explicit fail command. 


ERROR_BUFFER_OVERFLOW 
Buffer passed to system call too small to hold return data. 


ERROR_DISK_FULL 
Not enough space on the disk. 


ERROR _NO MORE SEARCH_HANDLES 
Cannot allocate another search structure and handle. 


ERROR_INVALID_TARGET_HANDLE 
Target handle in DosDupHandle invalid. 


ERROR_PROTECTION_VIOLATION 
Bad user virtual address. 


ERROR_VIOKBD_REQUEST 
Error on display write or keyboard read. 


ERROR_INVALID_CATEGORY 
Category for DevIOCtl not defined. 


ERROR_INVALID_VERIFY_SWITCH 
Invalid value passed for verify flag. 
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119 


120 


121 


122 


123 


124 


125 


126 


127 


128 


129 


130 


131 


132 


133 


134 


135 


136 


137 


ERROR_BAD_DRIVER_LEVEL 
Level four driver not found. 


ERROR_CALL_ NOT IMPLEMENTED 
Invalid function called. 


ERROR_SEM_TIMEOUT 
Time out occurred from semaphore API function. 


ERROR_INSUFFICIENT BUFFER 
Data buffer too small. 


ERROR_INVALID_NAME 
Illegal character or bad file-system name. 


ERROR_INVALID_LEVEL 
Non-implemented level for information retrieval or setting. 


ERROR_NO_VOLUME_ LABEL 
No volume label found with DosQFsInfo command. 


ERROR_MOD_NOT_FOUND 
Module handle not found with getprocaddr, getmodhandle. 


ERROR_PROC_NOT_FOUND 
Procedure address not found with getprocaddr. 


ERROR_WAIT_NO_ CHILDREN 
DosCwait finds no children. 


ERROR_CHILD_NOT_COMPLETE 
DosCwait children not terminated. 


ERROR_DIRECT_ACCESS_HANDLE 
Handle operation invalid for direct disk-access handles. 


ERROR_NEGATIVE_SEEK 
Attempting seek to negative offset. 


ERROR_SEEK_ON_DEVICE 
Application trying to seek on device or pipe. 


ERROR_IS_JOIN_TARGET 
Drive has previously joined drives. 


ERROR_IS_JOINED 
Drive is already joined. 


ERROR_IS_SUBSTED 
Drive is already substituted. 


ERROR_NOT_JOINED 
Cannot delete drive that is not joined. 


ERROR NOT SUBSTED 
Cannot delete drive that is not substituted. 
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138 


139 


140 


141 


142 


143 


144 


145 


146 


147 


148 


149 


150 


151 


152 


153 


154 


155 


ERROR_JOIN_TO_JOIN 
Cannot join to a joined drive. 


ERROR_SUBST_TO_SUBST 
Cannot substitute to a substituted drive. 


ERROR_JOIN_TO_SUBST 
Cannot join to a substituted drive. 


ERROR_SUBST_TO_JOIN 
Cannot substitute to a joined drive. 


ERROR_BUSY_DRIVE 

Specified drive is busy. 

ERROR_SAME_DRIVE 

Cannot join or substitute a drive to a directory on the same drive. 


ERROR_DIR_NOT_ROOT 
Directory must be a subdirectory of the root. 


ERROR_DIR_NOT_EMPTY 
Directory must be empty to use join command. 


ERROR_IS_SUBST_PATH 
Path specified is being used in a substitute. 


ERROR_IS_JOIN_PATH 

Path specified is being used in join. 
ERROR_PATH_BUSY 

Path specified is being used by another process. 


ERROR_IS_SUBST_TARGET 
Cannot join or substitute drive having directory that is target of a 
previous substitute. 


ERROR_SYSTEM_TRACE 
System trace error. 


ERROR _ INVALID EVENT COUNT 
DosMuxSemWait errors. 


ERROR_TOO_MANY_MUXWAITERS 
System limit of 100 entries reached. 


ERROR _INVALID_LIST FORMAT 
Invalid list format. 


ERROR_LABEL_TOO_LONG 
Volume label too big. 


ERROR_TOO_MANY_TCBS 
Cannot create another TCB. 
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156 


157 


158 


159 


160 


161 


162 


163 


164 


165 


166 


167 


168 


169 


170 


180 


181 


182 


183 


174 


ERROR_SIGNAL_REFUSED 
Signal refused. 


ERROR_DISCARDED 
Segment is discarded. 


ERROR_NOT_LOCKED 
Segment not locked. 


ERROR_BAD_THREADID_ADDR 
Bad thread-identity address. 


ERROR_BAD_ARGUMENTS 
Bad environment pointer. 


ERROR_BAD_PATHNAME 
Bad path name passed to exec. 


ERROR_SIGNAL_PENDING 
Signal already pending. 


ERROR_UNCERTAIN_MEDIA 
ERROR_I24 mapping. 


ERROR_MAX_THRDS_REACHED 
No more process slots. 


ERROR_MONITORS_NOT_SUPPORTED 
ERROR_I24 mapping. 


ERROR_UNC_DRIVER_NOT_ INSTALLED 
Default redir return code 


ERROR_LOCK_FAILED 
Locking failed. 


ERROR_SWAPIO_FAILED 
Swap IO failed. 


ERROR_SWAPIN_FAILED 
Swap in failed. 


ERROR_BUSY 
Busy. 


ERROR_INVALID_SEGMENT_NUMBER 
Invalid segment number. 


ERROR_INVALID_CALLGATE 
Invalid call gate. 


ERROR_INVALID_ORDINAL 
Invalid ordinal. 


ERROR_ALREADY_EXISTS 
Shared segment already exists. 
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184 


185 


186 


187 


188 


189 


190 


191 


192 


193 


194 


195 


196 


197 


198 


199 


200 


ERROR_NO_CHILD_PROCESS 
No child process to wait for. 


ERROR_CHILD_ALIVE_NOWAIT 
NoWait specified and child alive. 


ERROR_INVALID_FLAG_NUMBER 
Invalid flag number. 


ERROR_SEM_NOT_FOUND 
Semaphore does not exist. 


ERROR_INVALID_STARTING_CODESEG 
Invalid starting code segment, incorrect END (label) directive. 


ERROR_INVALID_STACKSEG 
Invalid stack segment. 


ERROR_INVALID_MODULETYPE 
Invalid module type; dynamic-link library file cannot be used as an 
application. Application cannot be used as a dynamic-link library. 


ERROR_INVALID_EXE_SIGNATURE 
Invalid EXE signature - file is DOS mode program or improper program. 


ERROR_EXE_MARKED_INVALID 
EXE marked invalid - link detected errors when application created. 


ERROR_BAD_EXE_FORMAT 
Bad EXE format - file is DOS mode program or improper program. 


ERROR_ITERATED_DATA_EXCEEDS_64K 
Iterated data exceeds 64K; more than 64K of data in one of the seg- 
ments of the file. 


ERROR_INVALID_MINALLOCSIZE 
Invalid minimum allocation size; size is specified to be less than the 
size of the segment data in the file. 


ERROR_DYNLINK_FROM_INVALID_RING 
Dynamic link from invalid privilege level; privilege level 2 routine 
cannot link to dynamic-link libraries. 


ERROR _IOPL_NOT_ENABLED 
IOPL not enabled - IOPL set to “NO” in CONFIG.SYS. 


ERROR_INVALID_SEGDPL 
Invalid segment descriptor privilege level - can only have privilege 
levels of 2 and 3. 


ERROR_AUTODATASEG_EXCEEDS_64K 
Automatic data segment exceeds 64K. 


ERROR_RING2SEG_MUST_BE_MOVABLE 
Privilege level 2 segment must be movable. 
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201 


202 


203 


204 


205 


206 


207 


208 


209 


210 


211 


212 


213 


214 


215 


Zhe 


218 


219 


ERROR_RELOC_CHAIN_XEEDS_SEGLIM 
Relocation chain exceeds segment limit. 


ERROR_INFLOOP_IN_RELOC_CHAIN 
Infinite loop in relocation chain segment. 


ERROR_ENVVAR_ NOT FOUND 
Environment variable not found. 


ERROR_NOT_CURRENT_CTRY 
Not current country. 


ERROR_NO_SIGNAL_SENT 
No signal sent - no process in the command subtree has a signal 
handler. 


ERROR_FILENAME_EXCED_RANGE 
Filename or extension greater than “8.3” characters. 


ERROR_RING2_STACK_IN_USE 
Privilege level 2 stack in use. 


ERROR_META_EXPANSION_TOO_LONG 
Meta (global) expansion is too long. 


ERROR_INVALID_SIGNAL_NUMBER 
Invalid signal number. 


ERROR_THREAD_ 1 INACTIVE 
Inactive thread. 


ERROR_INFO_NOT_AVAIL 
File system information not available for this file. 


ERROR _ LOCKED 
Locked error. 


ERROR_BAD_DYNALINK 
Attempted to execute non-family API in DOS mode. 


ERROR_TOO_MANY_MODULES 
Too many modules. 


ERROR_NESTING_NOT_ALLOWED 
Nesting not allowed. 


ERROR_ZOMBIE_PROCESS 
Zombie process. 


ERROR_STACK_IN_HIGH_MEMORY 
Stack in high memory. 


ERROR_INVALID_EXITROUTINE_RING 
Invalid exit routine ring. 
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ERROR_GETBUF_FAILED 
Get buffer failed. 


ERROR _FLUSHBUF_FAILED 
Flush buffer failed. 


ERROR_TRANSFER_TOO_LONG 
Transfer is too long. 


ERROR_NO_CHILDREN 
No child process. 


ERROR_INVALID_ SCREEN GROUP 
Invalid session. 


ERROR_BAD_PIPE 
Nonexistent pipe or bad operation. 


ERROR_PIPE_BUSY 
Pipe is busy. 


ERROR_NO_DATA 
No data available on non-blocking read. 


ERROR_PIPE_NOT_CONNECTED 
Pipe was disconnected by server. 


ERROR MORE DATA 
More data is available. 


ERROR_VC_DISCONNECTED 
Session was dropped due to errors. 


ERROR_CIRCULARITY_REQUESTED 
Renaming a directory that would cause a circularity problem. 


ERROR_DIRECTORY_IN_CDS 
Renaming a directory that is in use. 


ERROR_INVALID_FSD_NAME 
Trying to access nonexistent FSD. 


ERROR_INVALID_PATH 
Bad pseudo device. 


ERROR_INVALID_EA NAME 
Bad character in name, or bad cbName. 


ERROR_EA_ LIST INCONSISTENT 
List does not match its size, or bad EAs in list. 


ERROR_EA_LIST_TOO_LONG 
FEAList > 64K-1 bytes. 


ERROR_NO_META_MATCH 
String doesn’t match expression. 
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ERROR_NO_MORE_ITEMS 
DosQFSAttach ordinal query. 


ERROR_SEARCH_STRUC_REUSED 
DOS mode findfirst/next search structure reused. 


ERROR_CHAR NOT FOUND 
Character not found. 


ERROR_TOO_MUCH_STACK 
Stack request exceeds system limit. 


ERROR _INVALID_ATTR 
Invalid attribute. 


ERROR_INVALID_STARTING_RING 
Invalid starting ring. 


ERROR_INVALID_DLL_INIT_RING 
Invalid DLL INIT ring. 


ERROR_CANNOT_COPY 
Cannot copy. 


ERROR_DIRECTORY 
Used by DOSCOPY in doscalll. 


ERROR_OPLOCKED_FILE 
Oplocked file. 


ERROR_OPLOCK_THREAD_EXISTS 
Oplock thread exists. 


ERROR_VOLUME_CHANGED 
Volume changed. 


Reserved. 


ERROR_ALREADY_SHUTDOWN 
System already shutdown. 


ERROR EAS DIDNT _FIT 
EAS didnt fit. 


ERROR_INVALID_PROCID 
Invalid process identity. 


ERROR_INVALID_PDELTA 
Invalid priority delta. 


ERROR _ NOT DESCENDANT 
Not descendant. 


ERROR_NOT_SESSION_MANAGER 
Requestor not session manager. 


178 Appendix 


307 


308 


309 


310 


311 


312 


313 


314 


315 


316 


317 


318 


319 


320 


321 


322 


323 


324 


326 


ERROR INVALID _PCLASS 
Invalid P class. 


ERROR_INVALID_SCOPE 
Invalid scope. 


ERROR_INVALID_THREADID 
Invalid thread identity. 


ERROR_DOSSUB_SHRINK 
Cannot shrink segment—DosSubSet. 


ERROR_DOSSUB_NOMEM 
No memory to satisfy request—DosSubAlloc. 


ERROR_DOSSUB_OVERLAP 
Overlap of specified block with an allocated memory—DosSubFree. 


ERROR_DOSSUB_BADSIZE 
Bad size parameter - DosSubAlloc or DosSubFree. 


ERROR_DOSSUB_BADFLAG 
Bad flag parameter—DosSubSet. 


ERROR_DOSSUB_BADSELECTOR 
Invalid segment selector. 


ERROR_MR_MSG_TOO_LONG 
Message too long for buffer. 


ERROR_MR_MID_NOT_FOUND 
Message identity number not found. 


ERROR_MR_UN_ACC_MSGF 
Unable to access message file. 


ERROR_MR_INV_MSGF_FORMAT 
Invalid message file format. 


ERROR_MR_INV_IVCOUNT 
Invalid insertion variable count. 


ERROR_MR_UN_PERFORM 
Unable to perform function. 


ERROR_TS_WAKEUP 
Unable to wake up. 


ERROR_TS_SEMHANDLE 
Invalid system semaphore. 


ERROR_TS NOTIMER 
No timers available. 


ERROR_TS_ HANDLE 
Invalid timer handle. 
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ERROR_TS_ DATETIME 
Date or time invalid. 


ERROR_SYS_INTERNAL 
Internal system error. 


ERROR_QUE_CURRENT_NAME 
Current queue name does not exist. 


ERROR_QUE_PROC_NOT_OWNED 
Current process does not own queue. 


ERROR_QUE_PROC_OWNED 
Current process owns queue. 


ERROR_QUE_DUPLICATE 
Duplicate queue name. 


ERROR_QUE_ELEMENT_NOT_EXIST 
Queue element does not exist. 


ERROR_QUE_NO_MEMORY 
Inadequate queue memory. 


ERROR_QUE_INVALID_NAME 
Invalid queue name. 


ERROR_QUE_INVALID_PRIORITY 
Invalid queue priority parameter. 


ERROR_QUE_INVALID_HANDLE 
Invalid queue handle. 


ERROR_QUE_LINK_NOT_FOUND 
Queue link not found. 


ERROR_QUE_MEMORY_ERROR 
Queue memory error. 


ERROR_QUE_PREV_AT_END 
Previous queue element was at end of queue. 


ERROR_QUE_PROC_NO_ACCESS 
Process does not have access to queues. 


ERROR_QUE_EMPTY 
Queue is empty. 


ERROR_QUE_NAME_NOT_EXIST 
Queue name does not exist. 


ERROR_QUE_NOT_INITIALIZED 
Queues not initialized. 


ERROR_QUE_UNABLE_TO_ACCESS 
Unable to access queues. 
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ERROR_QUE_UNABLE_TO_ADD 
Unable to add new queue. 


ERROR_QUE_UNABLE_TO_INIT 
Unable to initialize queues. 


ERROR_VIO_INVALID_MASK 
Invalid function replaced. 


ERROR_VIO_PTR 
Invalid pointer to parameter. 


ERROR_VIO_APTR 
Invalid pointer to attribute. 


ERROR_VIO_RPTR 
Invalid pointer to row. 


ERROR_VIO_CPTR 
Invalid pointer to column. 


ERROR_VIO_LPTR 
Invalid pointer to length. 


ERROR_VIO_MODE 
Unsupported screen mode. 


ERROR_VIO_WIDTH 
Invalid cursor width value. 


ERROR _VIO_ATTR 
Invalid cursor attribute value. 


ERROR_VIO_ROW 
Invalid row value. 


ERROR_VIO_COL 
Invalid column value. 


ERROR_VIO_TOPROW 
Invalid TopRow value. 


ERROR _ VIO. BOTROW 
Invalid BotRow value. 


ERROR_VIO_RIGHTCOL 
Invalid right column value. 


ERROR_VIO_LEFTCOL 
Invalid left column value. 


ERROR_SCS_CALL 
Call issued by other than sm 


ERROR_SCS_ VALUE 
Value is not for save or restore. 
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ERROR_VIO_WAIT_FLAG 
Invalid wait flag setting. 


ERROR_VIO_UNLOCK 
Screen not previously locked. 


ERROR_SGS_NOT_SESSION_MGR 
Caller not session manager. 


ERROR_SMG_INVALID_SGID 
Invalid session identity. 


ERROR _ SMG INVALID SESSION ID 
Invalid session ID. 


ERROR_SMG NOSG 
No sessions available. 


ERROR_SMG NO_SESSIONS 
No sessions available. 


ERROR_SMG_ GRP NOT FOUND 
Session not found. 


ERROR_SMG SESSION NOT FOUND 
Session not found. 


ERROR_SMG_SET_TITLE 
Title sent by shell or parent cannot be changed. 


ERROR_KBD_PARAMETER 
Invalid parameter to keyboard. 


ERROR KBD NO_ DEVICE 
No device. 


ERROR_KBD_INVALID_IOWAIT 
Invalid I/O wait specified. 


ERROR_KBD_INVALID_LENGTH 
Invalid length for keyboard. 


ERROR _KBD_ INVALID ECHO MASK 
Invalid echo mode mask. 


ERROR_KBD_INVALID_INPUT_MASK 
Invalid input mode mask. 


ERROR_MON_INVALID_PARMS 
Invalid parameters to DosMon. 


ERROR_MON_INVALID_DEVNAME 
Invalid device name string. 


ERROR MON _ INVALID HANDLE 
Invalid device handle. 
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ERROR MON_BUFFER_TOO_SMALL 
Buffer too small. 


ERROR_MON_BUFFER_EMPTY 
Buffer is empty. 


ERROR_MON_DATA_TOO_LARGE 
Data record too large. 


ERROR_MOUSE_NO_DEVICE 
Mouse device closed (invalid device handle). 


ERROR MOUSE_INV_HANDLE 
Mouse device closed (invalid device handle). 


ERROR_MOUSE_INV_PARMS 
Parameters invalid for display mode. 


ERROR_MOUSE_CANT_RESET 
Function assigned and cannot be reset. 


ERROR_MOUSE_DISPLAY_PARMS 
Parameters invalid for display mode. 


ERROR _MOUSE_INV_ MODULE 
Module not valid. 


ERROR_MOUSE_INV_ENTRY_PT 
Entry point not valid. 


ERROR MOUSE_INV_MASK 
Function mask invalid. 


NO_ERROR_ MOUSE NO DATA 
No valid data. 


NO_ERROR MOUSE_PTR_ DRAWN 
Pointer drawn. 


ERROR_INVALID_FREQUENCY 
Invalid frequency for beep. 


ERROR NLS NO _COUNTRY_ FILE 
Cannot find COUNTRY.SYS file. 


ERROR_NLS_OPEN_FAILED 
Cannot open COUNTRY.SYS file. 


ERROR_NLS_NO_CTRY_CODE 
Country code not found. 


ERROR_NO_COUNTRY_OR_CODEPAGE 
Country code not found. 


ERROR_NLS TABLE TRUNCATED 
Table returned information truncated, buffer too small. 
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ERROR_NLS_BAD_ TYPE 
Selected type does not exist. 


ERROR_NLS_TYPE_NOT_FOUND 
Selected type not in file. 


ERROR_VIO_SMG_ONLY 
Valid from session manager only. 


ERROR_VIO_INVALID_ASCIIZ 
Invalid ASCIIZ length. 


ERROR_VIO_DEREGISTER 
VioDeRegister not allowed. 


ERROR_VIO_NO_POPUP 
Pop-up window not allocated. 


ERROR_VIO_EXISTING_POPUP 
Pop-up window on screen (NoWait). 


ERROR_KBD_SMG_ONLY 
Valid from session manager only. 


ERROR_KBD_INVALID_ASCIIZ 
Invalid ASCIIZ length. 


ERROR_KBD_INVALID_MASK 
Invalid replacement mask. 


ERROR_KBD_REGISTER 
KbdRegister not allowed. 


ERROR_KBD_DEREGISTER 
KbdDeRegister not allowed. 


ERROR_MOUSE_SMG_ONLY 
Valid from session manager only. 


ERROR_MOUSE_INVALID_ASCIIZ 
Invalid ASCHUZ length. 


ERROR_MOUSE_INVALID_MASK 
Invalid replacement mask. 


ERROR_MOUSE_REGISTER 
Mouse register not allowed. 


ERROR_MOUSE_DEREGISTER 
Mouse deregister not allowed. 


ERROR_SMG_BAD_ACTION 
Invalid action specified. 


ERROR_SMG_INVALID_CALL 
INIT called more than once or invalid session identity. 
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ERROR_SCS_SG_NOTFOUND 
New session number. 


ERROR _SCS_ NOT SHELL 
Caller is not shell. 


ERROR_VIO_INVALID_PARMS 
Invalid parameters passed. 


ERROR_VIO_FUNCTION_OWNED 
Save/restore already owned. 


ERROR_VIO_RETURN 
Non-destruct return (undo). 


ERROR_SCS_INVALID_ FUNCTION 
Caller invalid function. 


ERROR_SCS_NOT_SESSION_MGR 
Caller not session manager. 


ERROR_VIO_REGISTER 
Vio register not allowed. 


ERROR _ VIO NO MODE THREAD 
No mode restore thread in SG. 


ERROR_VIO_NO_SAVE_RESTORE_THD 
No save/rest thread in SG. 


ERROR_VIO_IN_BG 
Function invalid in background. 


ERROR_VIO_ILLEGAL_DURING_POPUP 
Function not allowed during pop-up window. 


ERROR_SMG NOT _BASESHELL 
Caller is not the base shell. 


ERROR_SMG_BAD_STATUSREQ 
Invalid status requested. 


ERROR_QUE_INVALID_WAIT 
NoWait parameter out of bounds. 


ERROR _VIO_ LOCK 
Error returned from Scroll Lock. 


ERROR_MOUSE_INVALID_IOWAIT 
Invalid parameters for IOWait. 


ERROR _VIO_INVALID_ HANDLE 
Invalid VIO handle. 


ERROR_VIO_ILLEGAL_DURING_LOCK 
Function not allowed during screen lock. 
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ERROR_VIO_INVALID_LENGTH 
Invalid VIO length. 


ERROR KBD INVALID HANDLE 
Invalid KBD handle. 


ERROR KBD NO MORE HANDLE 
Ran out of handles. 


ERROR KBD CANNOT CREATE KCB 
Unable to create Kcb. 


ERROR_KBD_CODEPAGE_LOAD_INCOMPL 
Unsuccessful code-page load. 


ERROR_KBD_INVALID_CODEPAGE_ID 
Invalid code-page identity. 
ERROR_KBD_NO_CODEPAGE_SUPPORT 
No code page support. 


ERROR_KBD_FOCUS_REQUIRED 
Keyboard focus required. 


ERROR_KBD_FOCUS_ALREADY_ACTIVE 
Calling thread has an outstanding focus. 


ERROR_KBD_KEYBOARD_BUSY 
Keyboard busy. 


ERROR_KBD_INVALID_CODEPAGE 
Invalid code page. 


ERROR_KBD_UNABLE_TO_FOCUS 
Focus attempt failed. 


ERROR SMG SESSION _NON_SELECT 
Session is not selectable. 


ERROR_SMG_SESSION_NOT_FOREGRND 
Parent/child session not foreground. 


ERROR_SMG_SESSION_NOT_PARENT 
Not parent of requested child. 


ERROR _ SMG INVALID _START_ MODE 
Invalid session start mode. 


ERROR_SMG_INVALID_RELATED_OPT 
Invalid session start related option. 


ERROR_SMG_INVALID_BOND_OPTION 
Invalid session bond option. 


ERROR_SMG_INVALID_SELECT_OPT 
Invalid session select option. 
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ERROR_SMG_START_IN_BACKGROUND 
Session started in background. 


ERROR_SMG_INVALID_STOP_OPTION 
Invalid session stop option. 


ERROR_SMG_BAD_RESERVE 
Reserved parameters not zero. 


ERROR_SMG_PROCESS_NOT_PARENT 
Session parent process already exists. 


ERROR_SMG_INVALID_DATA_LENGTH 
Invalid data length. 


ERROR SMG NOT BOUND 
Parent not bound. 


ERROR_SMG_RETRY_SUB_ALLOC 
Retry request block allocation. 


ERROR KBD DETACHED 
This call not allowed for detached PID. 


ERROR_VIO_DETACHED 
This call disallowed for detached pid. 


ERROR_MOU_DETACHED 
This call disallowed for detached pid. 


ERROR_VIO_FONT 
No font available to support mode. 


ERROR_VIO_USER_ FONT 
User font active. 


ERROR_VIO_BAD_CP 
Invalid code page specified. 


ERROR_VIO_NO_CP 
System displays do not support code page. 


ERROR_VIO_NA_CP 
Current display does not support code page. 


ERROR_INVALID_CODE_PAGE 
Invalid code page. 


ERROR_CPLIST_TOO_SMALL 
Code page list is too small. 


ERROR_CP_NOT_MOVED 
Code page not moved. 


ERROR_MODE_ SWITCH _INIT 
Mode switch initialization error. 
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ERROR_CODE_PAGE_NOT_FOUND 
Code page not found. 


ERROR_UNEXPECTED_SLOT_RETURNED 
Internal error. 


ERROR _ SMG _INVALID_ TRACE OPTION 
Invalid start session trace indicator. 


ERROR _VIO_INTERNAL_ RESOURCE 
VIO internal resource error. 


ERROR_VIO_SHELL_INIT 
VIO shell initialization error. 


ERROR_SMG_NO_HARD_ERRORS 
No session manager hard errors. 


ERROR_CP_SWITCH_INCOMPLETE 
DosSetCp unable to set KBD or VIO code page. 


ERROR_VIO_TRANSPARENT_POPUP 
Error during VIO pop-up window. 


ERROR _CRITSEC_OVERFLOW 
Critical section overflow. 


ERROR_CRITSEC_UNDERFLOW 
Critical section underflow. 


ERROR_VIO_BAD_RESERVE 
Reserved parameter is not zero. 


ERROR_INVALID_ADDRESS 
Bad physical address. 


ERROR_ZERO_SELECTORS_REQUESTED 
At least one selector must be requested. 


ERROR_NOT_ENOUGH_SELECTORS_AVA 
Not enough GDT selectors to satisfy request. 


ERROR _INVALID_SELECTOR 
Not a GDT selector. 


ERROR_SMG_INVALID_PROGRAM_TYPE 
Invalid program type. 


ERROR_SMG_INVALID_PGM_CONTROL 
Invalid program control. 


ERROR_SMG_INVALID_INHERIT_OPT 
Bad inherit option. 


ERROR_VIO_EXTENDED_SG 
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ERROR_VIO_NOT_PRES_MGR_SG 
ERROR_VIO_SHIELD_OWNED 
ERROR_VIO_NO_MORE_HANDLES 
ERROR_VIO_SEE_ERROR_LOG 
ERROR_VIO_ASSOCIATED_DC 
ERROR_KBD_NO_CONSOLE 
ERROR_MOUSE_NO_CONSOLE 
ERROR_MOUSE_INVALID_HANDLE 
ERROR_SMG_INVALID_DEBUG_PARMS 
ERROR_KBD_EXTENDED_SG 
ERROR_MOU_EXTENDED_SG 
ERROR_SMG_INVALID_ICON_FILE 
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index 





A 
adapters, attributes supported by video, 
149-152 


B 
Base Video Handler (BVH), 87 


D 
double-byte character code (DBCS), 5, 19 


E 


error messages, 167-189 


F 

FAPI, 2, 36, 76 

functions 
KBD, 1-34 
MOU, 35-73 
VIO, 75-166 


G 
graphical user interface (GUI), xiii 


H 


Hauser, Carl, xi 


K 
KbdCharln, 3-5 
KbdClose, 6 
KbdDeRegister, 7 
KbdFlushBuffer, 8 
KbdFreeFocus, 9 
KbdGetCp, 10 
KbdGetFocus, 11 
KbdGetHWld, 12-13 
KbdGetStatus, 14-16 
KbdOpen, 17 
KbdPeek, 18-20 
KbdRegister, 21-22 
KbdSetCp, 23-24 
KbdSetCustxt, 25 
KbdSetFgnd, 26 
KbdSetStatus, 27-29 
KbdStringln, 30-31 
KbdSynch, 32 


KbdXlate, 33-34 
keyboard (KBD) functions, 1-34 

binds logical to physical keyboard, 11 

call list, 2 

clears keystroke buffer, 8 

closes existing logical keyboard, 6 

creates new logical keyboard, 17 

deregisters keyboard subsystem, 7 

frees logical-to-physical keyboard bond, 
9 

gets current state of keyboard, 14-16 

installs translate table, 25 

queries code page, 10 

raises priority of keyboard’s thread, 26 

reads character strings from keyboard, 
30-31 

registers keyboard subsystems, 21-22 

returns character data records, 3-5, 
18-20 

returns hardware identification value, 
12-13 

sets code page, 23-24 

sets characteristics of keyboard, 27-29 

synchronizes access from subsystem to 
device driver, 32 

translates scan codes, 33-34 


L 
logical video buffer (LVB), 81 


M 
MouClose, 37 
MouDeRegister, 38 
MouDrawPtr, 39 
MouFlushQue, 40 
MouGetDevStatus, 41 
MouGetEventMask, 42-43 
MouGetNumButtons, 44 
MouGetNumMickeys, 45 
MouGetNum@QueE], 46 
MouGetPtrPos, 47 
MouGetPtrShape, 48-50 
MouGetScaleFact, 51 
MoulnitReal, 52-53 
MouOpen, 54-55 
MouReadEventQue, 56-58 
Moukegister, 59-61 
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MouRemovePtr, 62-63 
mouse (MOU) functions, 35-73 
assigns event masks, 66-67 
assigns new pair of scaling factors, 72 
call list, 36 
closes mouse device, 37 
copies pointer shape, 48-50 
deregisters mouse subsystem, 38 
determines current row/column 
coordinates, 47 
directs mouse driver to empty queue, 
40 
mouse pointer draw support for DOS, 
52-53 
notifies mouse device driver, 39, 62-63 
opens mouse device, 54 
reads events from FIFO queue, 56-58 
registers mouse subsystem, 59-61 
returns current status for queue, 46 
returns current value of queue mask, 
42-43 
returns number of buttons, 44 
returns number of mickeys, 45 
returns scaling factors, 51 
returns status flags for device driver, 
41 
sets new row/column coordinates, 68 
sets pointer shape/size, 69-71 
sets status flags, 64-65 
synchronous access for subsystem to 
device driver, 73 
MouSetDevStatus, 64-65 
MouSetEventMask, 66-67 
MouSetPtrPos, 68 
MouSetPtrShape, 69-71 
MouSetScaleFact, 72 
MouSynch, 73 


V 
video (VIO) functions, 75-166 

activates/deactivates ANSI support, 
138 

allows graphics mode application 
notification, 108-109 

allows subsystem notification, 102-105 

call list, 76-77 

cancels VioModeWait, 106-107 

cancels VioSavRedrawWait, 123-124 

deregisters subsystem, 78 

downloads display fonts, 144-145 

ends temporary screen, 79 

gets addressability to buffer, 97-98 

issues temporary screen message, 110- 
112 

notifies application to save/redraw, 
125-126 
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queries code page, 88 
reads strings from display, 117-118 
reads strings from screen, 115-116 
registers alternate video subsystems, 
119-122 
releases buffer, 137 
requests ownership of buffer, 127-128 
returns address of logical video buffer, 
81-82 
returns current ANSI status on/off, 80 
returns current settings, 99-101 
returns cursor coordinates, 89 
returns cursor type, 90-91 
returns font table or font used, 92-93 
returns mode of display, 94-96 
returns video display configuration, 83- 
87 
scrolls down, 129-130 
scrolls left, 131-132 
scrolls right, 133-134 
scrolls up, 135-136 
Session Manager control/print screen, 
114 
Session Manager print screen, 113 
sets code page, 139-140 
sets cursor coordinates, 141 
sets cursor type, 142-143 
sets different state structures, 153-156 
sets display mode, 146-152 
updates buffer, 157 
writes attributes to display, 162 
writes cell string to display, 158 
writes cells to display, 163 
writes characters to display, 164 
writes character string to display, 159, 
165-166 
writes character string with attributes 
to display, 160-161 
video display mode, attributes supported 
by adapters, 149-152 
VioColorReg, 100-101, 154-155 
VioDeRegister, 78 
VioEndPopUp, 79 
VioGetAnsi, 80 
VioGetBuf, 81-82 
VioGetConfig, 83-87 
VioGetCp, 88 
VioGetCurPos, 89 
VioGetCurType, 90-91 
VioGetFont, 92-93 
VioGetMode, 94-96 
VioGetPhysBuf, 97-98 
VioGetState, 99-101 
VioGlobalReg, 102-105 
VioIntensity, 100, 154 
VioModeUndo, 106-107 
VioModewWait, 108-109 


VioOverScan, 100, 154 
VioPalState, 99, 153 
VioPopUp, 110-112 
VioPrtScr, 113 
VioPrtScToggle, 114 
VioReadCellStr, 115-116 
VioReadCharStr, 117-118 
VioRegister, 119-122 
VioSaveRedrawWait, 125-126 
VioSavRedrawUndo, 123-124 
VioScrLock, 127-128 
VioScrollDn, 129-130 
VioScrollLf, 131-132 
VioScrollRt, 133-134 
VioScrollUp, 135-136 
VioScrUnLock, 137 
VioSetAnsi, 138 

VioSetCp, 139-140 
VioSetCurPos, 141 


VioSetCurType, 142-143 
VioSetFont, 144-145 
VioSetMode, 146-152 
VioSetState, 153-156 
VioSetTarget, 101, 155 
VioSetUlineLoc, 101, 155 
VioShowBuf, 157 
VioWrtCellStr, 158 
VioWrtCharStr, 159 
VioWrtCharStrAtt, 160-161 
VioWrtNAttr, 162 
VioWrtNCell, 163 
VioWrtNChar, 164 
ViowWrtTTY, 165-166 


X 
XPM, 2, 36, 76 
xWPM, 2, 36, 76 
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